Commit graph

37 commits

Author SHA1 Message Date
Julian Knutsen
77ab980790
ci(bazel): run the hook-timeout-backends check under Bazel; test-nix stops running tests (#7357)
checks.nix's hook-timeout-backends (the tracked git hook shims against
real GNU/uutils/busybox/toybox timeout implementations, with and without
perl, under dash, bash and busybox ash: 240 cases) was the one test PR
Risk's test-nix ran on a GitHub runner, through `nix flake check`. It is
now //tests/hook_timeout_backends:hook_timeout_backends_test, an sh_test
(pr-core-only) that the bazel-test lane runs remotely on every PR: the
static uutils 0.12.0, busybox 1.35.0 and toybox 0.8.15 binaries come in
sha256-pinned through MODULE.bazel; dash, bash, perl and GNU coreutils
from the executor, failing (not skipping) when one is missing.

checks.nix goes and flake.nix declares no checks, so test-nix's
`nix run .#default` + `nix flake check` is a packaging check (build the
package Nix users install, evaluate every flake output), not a test.
TestHookTimeoutBackendsRunUnderBazel pins the target and that no flake
check comes back.

ga-96smfk.22

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-07 11:05:39 +00:00
Julian Knutsen
368b225eef
docs(bazel): make bazel test the primary build and test path (ga-96smfk.23) (#7348)
Bazel is beads' build and test system: bazel.yml's lanes gate every PR,
and nogo (lint + vet), gofmt and the repository guards exist only as
Bazel targets. The docs, the Makefile and the hooks now say so.

Makefile: `make test` runs bazel.yml's test lane (`bazel test //...
--config=ci`), `make check` adds the testing.Short policy and the
`make ci-pr-lint` nogo gate, and `make check-docs` runs the docsync and
doc-freshness Bazel targets before the pinned-release CLI flag check.
BAZEL_FLAGS passes --config=fork-cache or --config=remote-exec through.
The plain-Go recipes stay as explicit twins: test-go, check-go,
check-docs-go. No workflow called the primary names, and
TestWorkflowsNameTheirTestEngine keeps it that way.

Hooks: pre-push runs scripts/pre-push-suite.sh for branch pushes whose
commits change Go or Bazel inputs: the test lane with
--config=remote-exec when some rc names an executor, else
--config=fork-cache. Without bazel, or with BD_PREPUSH_SUITE=go, it runs
make test-go under a banner saying that is not what CI gates on.

Docs: AGENTS.md, CONTRIBUTING.md, engdocs/TESTING.md (a per-lane command
table and the fork-cache/remote-exec setup), README, RELEASING, the PR
template and the .bazelrc header. Bazelisk is a required prerequisite;
go test is an inner-loop convenience CI does not enforce.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-07 07:46:02 +00:00
Julian Knutsen
a4509deb2d
ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341)
* ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18)

Lint and vet now run as nogo inside the Bazel build, so they gate wherever
the Bazel lanes execute (rbe-west), and the golangci-lint and go vet jobs
leave pr.yml and main.yml.

- //tools/nogo (own go.mod, joined to beads' for go_deps only through
  gazelle.go.work): go test's vet checks (cmd/go's defaultVetFlags, the set
  scripts/ci/go-test-vet.sh ran) plus the eight linters .golangci.yml
  enables, each a wrapper over the library version golangci-lint v2.10.1
  uses (depguard, errcheck, forbidigo, gosec, misspell, sloglint, unconvert,
  unparam).
- .golangci.yml stays the single lint policy: Bazel embeds it and
  tools/nogo/internal/golangci applies it as golangci-lint does (enabled
  set, settings, run.tests: false as library-unit-only analysis, lax
  generated-file detection, path/path-except/text exclusion rules), with
  strict decoding so an unimplemented key fails the build.
- gascity's rules_go //nolint-range patch and x/tools ctrlflow patch,
  byte-identical.
- Windows/darwin: cross-configured, not a golangci leg. The pure lane's
  release cross-compile (//tools/bazel:release_cross, every library and
  binary for all eight release platforms, cgo off) runs nogo on every
  compile, a superset of golangci-lint's windows and darwin legs.
  scripts/pr-lint (make ci-pr-lint, bd preflight) runs `bazel build
  --config=nogo //...` plus release_cross for windows_amd64,darwin_arm64.
  release_cross skips tools/nogo, a separate Go module `go build ./...`
  never compiled.
- pr.yml: scripts-go-checks (vet) and pr-lint-wrapper (x3) are gone, with
  their ci-gate entries; main.yml: pr-lint-wrapper (x6) and go-vet-cache.
  scripts/ci/go-test-vet.sh and install-golangci-lint.sh are deleted.
- pre-commit hook and .pre-commit-config.yaml run `make lint-changed
  LINT_CHANGED_SCOPE=staged` (nogo over the staged packages); Makefile adds
  lint, vet and lint-changed. pr-lint.sh no longer runs gofmt
  (//scripts/repochecks:fmt_test owns it; ga-96smfk.41).
- internal/testutil/integration: five gosec findings in integration-tagged
  library files golangci-lint never built, now linted by the integration
  lanes, carry reasoned //nolint directives.

Parity: with the exclusion rules removed, golangci-lint and nogo report the
same 3,916 findings natively and 3,859 each for windows and darwin (file,
line, linter, text); with .golangci.yml as committed both report none.

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

* ci(bazel): equivalence.py leaves nested Go modules' tests out of go test's set

tools/nogo is its own Go module, so `go test ./...` in the root never runs
its tests; Bazel's unit lane does. Its packages are neither expected nor
extra.

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

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-07 05:17:22 +00:00
Julian Knutsen
55f96b3f5e
docs(contributing): recommend issues when they add context instead of requiring one per PR (#7323)
#7223 made a linked, documented issue mandatory for every PR. That is
the right default for user-visible bugs and changes worth discussing,
but it adds ceremony to small, self-explanatory fixes without adding
context.

AGENTS.md, CONTRIBUTING.md, ROADMAP.md, the PR template and the feature
form now advise filing an issue when it adds context and let small fixes
go straight to a PR whose description explains the why. End-to-end
evidence is still required, and Closes #N is used when an issue exists.
No CI check or ruleset enforced the requirement; scripts/pr-preflight.sh
already only warns when a PR has no closing issue.

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-06 23:29:09 +00:00
Julian Knutsen
0773e6334e
docs(agents): contributor-only agent instructions and documented-issue intake (#7223)
Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue.

- Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files.
- Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup.
- ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228).
- docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names.

Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-05 08:43:53 +00:00
Julian Knutsen
6be9c861a8
ci: advisory workflows on Blacksmith with restore-only caches, folded matrices, path filters (F7c) (#7147)
* ci(advisory): move Conformance/Regression/Migration/Smoke/Docs/Proxied-Local to Blacksmith, fold matrices, path-filter, drop redundant nix-build PR trigger (F7c)

Reduces per-PR GitHub-hosted job load for advisory (non-required) workflows
per the "PR CI -> 5 min" plan, slice F7c. None of these workflows gate the
required CI Gate / PR Risk Gate checks.

- conformance.yml: same-repo PR/merge_group runs move to Blacksmith
  (4vcpu); PR trigger gets the shared "upgrade-relevant code" path filter
  (any non-test Go change or build input); also now runs on push to main.
- regression.yml: fold detect-regression-need into regression's first step
  (gated via `if:`), eliminating a whole job; move to Blacksmith.
- migration-test.yml: fold the 14-version x cache-identity matrix into 3
  shards (src/pre-dolt/dolt-runtime), looping every version in a shard via
  a new "Verify explicit historical upgrades" step so a bad version does
  not hide the rest; gains the shared path filter; move to Blacksmith.
- cross-version-smoke.yml: fold the 1-job-per-version matrix into chunks of
  5 (delegated to upgrade-smoke-test.sh's native SMOKE_VERSIONS support);
  gains the shared path filter; move to Blacksmith.
- docs-mintlify.yml, proxied-local-smoke.yml: move to Blacksmith
  (2vcpu/4vcpu); add missing timeout-minutes where absent.
- nix-build.yml: drop the pull_request trigger — pr-risk.yml's required
  test-nix job (nix run + nix flake check) is a strict superset of
  `nix build .#default`, pinned by a new regression test.
- main.yml: add blacksmith-setup-go-cache, a push-to-main-only job that
  warms setup-go's implicit cache with cache: true, since Blacksmith
  runners cannot see GitHub-saved actions/cache entries that the six
  workflows above now rely on via setup-go's own caching. Carves a scoped,
  documented exception into assertPinnedGoCacheActions for this one job;
  every other setup-go step in main.yml/pr.yml/pr-risk.yml still must pin
  cache: false.

Forks and Dependabot PRs are unaffected (still ubuntu-latest, no secrets),
via the same conditional runner expression used elsewhere in the repo.

New policy tests in scripts/ci_f7c_advisory_test.go pin: path-filter
identity across the three filtered workflows, full version-set coverage
of the migration-harness fold (no scenario dropped), the per-shard/per-
chunk retry-all-versions-even-on-failure loop, fork/dependabot runner
selection semantics, no Blacksmith job reads secrets, and that the new
cache-seed job exists and that its six consumers don't disable the cache
it warms. All new tests and their underlying behaviors were mutation-
tested (each fails when the behavior it pins is reverted).

Caveat for rollout: the Blacksmith cache-seed job assumes Blacksmith
labels have branch-protected cache isolation from fork/untrusted PRs at
the org level (spec-f7.md Group B precondition) — this needs confirming
with an org admin before merge, since the seed job's cache becomes shared
infrastructure the six advisory workflows implicitly trust.

Replayed the last 60 merged PRs' changed-file lists against the new path
filter: 20/60 would now skip Conformance/Migration/Smoke (matches the
spec's estimate), and none of the 60 touched non-test Go code while being
classified as skip.

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

* fix(ci,advisory): F7c review B1/B2 - pin migration fallback, restore-only Blacksmith caches

B1: migration-test.yml's non-Blacksmith historical-upgrades fallback was
`ubuntu-latest`, which actions/runner-images#14748 schedules to move from
24.04 to 26.04 starting 2026-10-19. 26.04 drops libicu74, which the v0.55.4
fixture's ICU ABI depends on (and which "Install test dependencies" installs
explicitly). Pin the fallback to the literal `ubuntu-24.04` label instead, and
add the matching sameRepoBlacksmith4vcpuNoble constant so the pin itself is
tested. Confirmed via `git show <pre-F7c>` that none of the other five
workflows F7c touched ever had a pinned-OS fallback, so this regression was
scoped to migration-test.yml only.

B2: Blacksmith cannot see GitHub-hosted cache entries, and a same-repo PR
writing a cache entry another PR or main later reads back unverified is a
poisoning vector. Make every advisory consumer (conformance, regression,
migration-test, cross-version-smoke, docs-mintlify, proxied-local-smoke)
disable setup-go's own implicit cache on self-hosted runners and restore-only
from a self-defined `blacksmith-sg-v1-...` key namespace (not setup-go's own
implicit key, so there is no dependency on Blacksmith's $ImageOS matching
GitHub-hosted resolution). Only main.yml's new blacksmith-setup-go-cache job
(push-to-main only, always trusted) saves: it always restores, unconditionally
re-runs every warm-up command (no longer gated on a cache hit, so a stale or
partial restore self-heals), and always saves under the same key. Delete the
now-unneeded goCacheImplicitCacheExceptions carve-out in ci_workflow_test.go.

Also convert cross-version-smoke.yml's smoke-binaries-* and regression.yml's
regression-baseline-* caches from a monolithic actions/cache (auto-saves on
any miss) into an explicit restore (always, modulo the job's own gate) / save
(gated off pull_request) pair, closing the same poisoning vector for
per-release binaries. migration-test.yml's historical-dolt-* cache is left
unchanged: it is already checksum-verified on every read by
scripts/migration-test/lib/binary.sh.

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

* test(ci,advisory): F7c review SF - behavioral tests, path filters, F7a naming coordination

Replace substring-matching tests with behavioral ones that execute the real
embedded bash/jq against synthetic input, closing the reviewer's 12 surviving
mutations:

- TestMigrationHarnessLoopExecutesBehaviorally runs the real "Verify explicit
  historical upgrades" step against a stub run.sh: every version in a shard
  still runs after an earlier one fails (closes `exit 0`/`break` mutations),
  failures are ::error:: annotated and written to $GITHUB_STEP_SUMMARY, a bad
  or empty SHARD_VERSIONS fails closed without ever invoking run.sh, and a
  hung version is bounded by `timeout --kill-after` without hiding the version
  queued after it. The step's env now exports SHARD so its run: body has no
  literal ${{ }} GH-expression syntax left for a test harness to choke on.
- TestMigrationHarnessCacheHashMatchesDerivation pins each shard's cache-hash
  against sha256(join(",", <shard's cache-identity strings>))[:16], recovered
  from the pre-fold 14-entry table (git show 362eecc6bf), closing a stale-
  cache-hash mutation.
- TestMigrationHarnessDoltRuntimeStepGatedByShard pins the exact gate
  expression for "Install Dolt test runtime".
- TestCrossVersionSmokeChunksEveryResolvedVersion now executes the real jq
  chunking and join programs (via the new ghExtractJQProgram helper) against
  synthetic version lists of several sizes, and asserts the smoke step's run:
  command is an exact match - closing jq-slice-off-by-one and
  dropped-SMOKE_VERSIONS mutations a substring check could not catch.
- TestRegressionStepsAfterDetectAreGated pins that every step after
  regression.yml's detect step stays gated on
  steps.detect.outputs.run_regression == 'true', closing an
  ungated-regression-step mutation.
- TestBlacksmithSetupGoSeedExistsForAdvisoryConsumers,
  TestAdvisoryBlacksmithConsumersAreCacheRestoreOnly (replacing
  TestAdvisoryBlacksmithConsumersKeepImplicitSetupGoCache),
  TestBlacksmithSetupGoCacheKeysMatchAcrossSeederAndConsumers, and
  TestAdvisoryBinaryCachesAreRestoreAlwaysSavePRGated cover the B2
  restore-only/seeder-saves cache topology end to end, including a
  seeder/consumer key-match check and scoping the "no save in a consumer job"
  check to the blacksmith-sg-v1- namespace specifically so migration-test.yml's
  legitimate, checksum-verified historical-dolt-* cache is not flagged.

Path filters: add scripts/migrate-legacy-to-current.sh to migration-test.yml
(the harness invokes it directly but it lives outside scripts/migration-test/)
and internal/storage/embeddeddolt/conformance_test.go plus backend/conformance/**
to conformance.yml, with a new TestConformancePushPathsMatchPullRequestPaths
pinning push.paths and pull_request.paths stay identical.

Coordination with F7a (ci/f7a-blacksmith-fold, lands before F7c): F7a
independently defines its own sameRepoBlacksmith4vcpu/2vcpu constants and a
TestSameRepoBlacksmithExpressionSemantics, and is moving a real GH-Actions
expression evaluator into a shared scripts test helper file. Per the
coordinator, rename this branch's same-named test to
TestF7cAdvisorySameRepoBlacksmithExpressionSemantics (deliberately left as the
same simple literal mirror it always was, not a competing evaluator) so it
does not collide with F7a's helper on rebase; at rebase time this test should
be reduced or replaced in favor of F7a's shared evaluator.

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

* docs(ci): update stale nix-build PR-trigger and renamed check-name references (F7c review S6)

F7c (bb81136203) dropped nix-build.yml's pull_request trigger as redundant
with PR Risk's test-nix job, and folded cross-version-smoke.yml's one-job-
per-version matrix into one job per 5-version chunk. Update the docs that
still described the old topology:

- CONTRIBUTING.md: nix build .#default no longer runs on PRs; point at PR
  Risk's required test-nix job instead.
- update-vendor-hash.yml: same correction in its header comment and the
  GITHUB_TOKEN-retrigger caveat.
- engdocs/CI_TEST_SURFACE_AUDIT.md: migration-test.yml now also runs on PRs
  (path-filtered, advisory) across 3 shards instead of 14 per-version legs;
  nix-build.yml's row now reflects push-to-main-only.
- engdocs/CI_REQUIRED_CHECK_TOPOLOGY.md: replace `Upgrade smoke
  (<version> -> candidate)` with the current `Upgrade smoke (chunk N)` job
  name in both the "do not require directly" list and the Cross-Version
  Smoke section; rewrite the Nix Build section to describe nix-build.yml as
  push-to-main-only (no longer a PR check to warn about requiring directly)
  and remove the now-unreachable `nix build .#default` bullet from the
  "do not require" list.

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

* ci(advisory): rebase onto F7a shared Blacksmith helper, drop duplicate const/evaluator

F7a (PR #7139, ci/f7a-blacksmith-fold) landed its own sameRepoBlacksmith4vcpu
const and TestSameRepoBlacksmithExpressionSemantics, plus a real GitHub
Actions expression evaluator (evalGHExpr/mustEvalGHRunsOn) in a new shared
scripts/ci_blacksmith_runner_test.go. This branch rebased onto
origin/ci/f7a-blacksmith-fold and reconciles the two:

- Removed this branch's duplicate sameRepoBlacksmith4vcpu definition in
  ci_workflow_test.go (rebase conflict); it's now served solely by F7a's
  shared const. sameRepoBlacksmith4vcpuNoble (F7c's B1 fix, fallback pinned
  to ubuntu-24.04 instead of ubuntu-latest) is kept as its own const, as
  instructed, since it is F7c-specific and not shared.
- Replaced TestF7cAdvisorySameRepoBlacksmithExpressionSemantics's
  hand-written Go mirror of the same-repo Blacksmith boolean logic with real
  evaluation of each F7c advisory job's actual, as-parsed runs-on expression
  text via F7a's evalGHExpr/mustEvalGHRunsOn, across the same event-shape
  truth table F7a's own test uses (same-repo/fork/dependabot/deleted-fork-
  head/merge_group/push/pull_request_target/schedule/workflow_dispatch).
  This covers all 8 F7c advisory Blacksmith jobs, including
  migration-test.yml's historical-upgrades job falling back to the literal
  ubuntu-24.04 label rather than ubuntu-latest. Confirmed via a cp-backed
  mutation (flipping the Noble fallback back to ubuntu-latest) that this new
  test, unlike the deleted hand-written mirror, actually catches a
  regression in the real expression text.
- Merged two more rebase conflicts in ci_workflow_test.go: the
  assertNoUnmanagedGoCacheSteps main.yml allowlist (F7a's
  windows-test-binaries-cache plus F7c's blacksmith-setup-go-cache) and a
  subsequent non-conflicting-but-incomplete 3-way merge of
  TestSameRepoBlacksmithRunners' main.yml entry (added
  windows-test-binaries-cache alongside blacksmith-setup-go-cache so the "no
  other Blacksmith label leaks" sweep covers both).

Did not merge TestBlacksmithAdvisoryJobsReadNoSecrets into F7a's
TestBlacksmithJobsReadNoSecrets (ci_workflow_test.go) even though the shared
helper file's doc comment suggests it; out of scope for this round per the
coordinator's explicit instructions, left as a follow-up.

Re-ran full verification after rebase + reconciliation: go build/vet/test
./scripts/..., bazel --nohome_rc test //scripts:scripts_test, actionlint
-shellcheck=shellcheck across all touched workflows, make ci-pr-policy, make
bazel-sync-check - all green. gofmt -l clean.

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

* fix(ci,advisory): close F7c re-review blocker X1 and S1-S5/N1 gaps

Re-review (~/beads-bazel-plan/f7c/rereview.md) found one blocker and five
should-fix gaps against ci/f7c-advisory-workflows:

X1 (blocker): migration-test.yml's historical-dolt-* cache was still a bare
actions/cache that auto-saves on any key miss on Blacksmith for same-repo
PRs. tar -P extraction plus lib/binary.sh's cp -f following a planted
symlink can redirect a write before sha256 verification ever runs, so the
"checksum-verified" exemption was unsound. Converted to the same
restore-always/save-off-PR split as smoke-binaries-*/regression-baseline-*,
dropped the exemption comments, and added it to advisoryBinaryCaches.

S1: TestRegressionDetectStepBehavioral executes regression.yml's detect
step's actual bash against a scratch git repo, closing mutation M13 (detect
step hard-wired to emit run_regression=false).

S2: TestBlacksmithReachableAdvisoryJobsNeverSaveACache sweeps every job in
every F7c advisory workflow (plus main.yml) whose runs-on resolves to a
Blacksmith label under a same-repo pull_request/merge_group context, and
fails on any bare actions/cache, any un-gated actions/cache/save, or any
setup-go/setup-node/setup-python step that would still cache there. Also
added a job-level `if: github.event_name == 'push' && github.ref ==
'refs/heads/main' && github.repository == 'gastownhall/beads'` guard to
main.yml's seeder job (TestBlacksmithSeederGuardedAgainstPullRequest) so a
future pull_request/merge_group trigger on main.yml can't turn the seeder
into a same-repo-PR-reachable cache writer.

S3: advisoryBinaryCaches' save-gate check is now exact-equality, not
strings.Contains, so a `... || true` gate can no longer slip past it.

S4: conformance.yml's path filters now include
internal/storage/embeddeddolt/test_fixture_test.go, which holds TestMain
for the whole package (moved out of conformance_test.go) and was previously
excluded by the blanket !**_test.go negation.

S5: main.yml's blacksmith-setup-go-cache seeder keyed its save on
github.sha, so every push to main - regardless of whether go.sum changed -
wrote a new multi-GB ~/go/pkg/mod + ~/.cache/go-build entry, risking LRU
eviction of F7a's own Blacksmith-seeded caches. Added a "Compute cache
date" step and keyed on the UTC calendar day instead, capping writes to at
most once per day; the same step/key was added to all 6 consumers so their
restore key stays byte-identical to the seeder's save key
(TestBlacksmithSetupGoCacheKeysMatchAcrossSeederAndConsumers).

N1: flipped `cache: ${{ runner.environment != 'self-hosted' }}` to
`cache: ${{ runner.environment == 'github-hosted' }}` on setup-go's own
implicit cache across all 7 call sites, so an empty/unknown
runner.environment value fails closed (caching off) instead of open.

Verification: go build/vet/test ./scripts/..., bazel --nohome_rc test
//scripts:scripts_test, actionlint -shellcheck=shellcheck
.github/workflows/*.yml, make ci-pr-policy, make bazel-sync-check all pass.

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

* fix(ci,advisory): close merge_group gap in binary-cache save gates

Running TestBlacksmithReachableAdvisoryJobsNeverSaveACache against every
Blacksmith trust context it is reachable under (instead of stopping at the
first match found, which made the check's coverage depend on Go's
randomized map iteration order) surfaced a real gap the S2 sweep was meant
to close: smoke-binaries-*, regression-baseline-* and historical-dolt-*'s
save gates were all `if: github.event_name != 'pull_request'`, a deny-list
that also admits a hypothetical future merge_group event. All three jobs'
runs-on expressions already resolve to a Blacksmith label under
merge_group, so a merge_group run would have been able to write those
caches too - the same same-repo-writer risk X1 closed for pull_request,
just not currently reachable since none of these three workflows has an
`on: merge_group:` trigger today.

Changed all three save gates to an exact allow-list of the triggers they
actually intend to write from (push, workflow_dispatch) rather than a
deny-list of the one trigger they don't. Updated
TestAdvisoryBinaryCachesAreRestoreAlwaysSavePRGated's wantSaveIf strings to
match, and made TestBlacksmithReachableAdvisoryJobsNeverSaveACache check
every blacksmithTrustContexts entry per job (sorted for determinism)
instead of breaking on the first Blacksmith-reachable context, so this
class of context-dependent gate gap can't hide behind map iteration order
again.

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

* test(ci,advisory): directly assert main.yml has no PR-reachable trigger

TestBlacksmithSeederGuardedAgainstPullRequest's job-level guard defuses the
vulnerability structurally, but a mutation that only edits main.yml's on:
block (adding pull_request:) without touching the job-level if: was not
caught by any existing test (confirmed: mutate.py's N6 probe survived).

Add TestMainWorkflowHasNoSameRepoPRReachableTrigger, the direct half of
F7c review fix S2's "pin the seeder's trust boundary" ask: assert main.yml's
on: has none of pull_request/pull_request_target/merge_group/workflow_run,
and still has push. Confirmed this kills N6 (manually applied and reverted
via a cp backup).

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

* build(bazel): auto-sync BUILD files

Applied from the bazel-sync-patch artifact of https://github.com/gastownhall/beads/actions/runs/37159233834
(`make bazel-sync`: gazelle, tools/bazel/go_srcs.py, bazel mod tidy).
Only BUILD.bazel, MODULE.bazel and MODULE.bazel.lock are ever pushed; see
scripts/bazel-autofix-push.sh.

---------

Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-10-03 16:03:39 -07:00
ecuthiell
02a416cc73
fix: make release-version checks shell-free (#5614)
* fix: make release-version checks shell-free (#5533)

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell

* fix(release): preserve checker status and explain gate failures (saa-cgh.16)

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* docs: retain release-pinned CLI references (saa-cgh.16)

Preserve corrected live preflight help while generated references continue to match docs/cli-docs.pin v1.2.2. Fix the exact two-line hosted docs-policy failure without changing pin authority.

Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell

* fix(versioncheck): carry base's release gates into the Go checker

The base branch gained three release-metadata gates in scripts/check-versions.sh
after this PR's merge point (release: prep v1.3.0, b3ef65c854): the Copilot
plugin manifest, the four winres.json Windows PE version fields, and
manifest.xml's assemblyIdentity version. This PR replaces that shell body with
the Go authority, so adopting it as-written would have silently dropped all
three — each one guards a file whose bump is a sed anchored on the old value,
so a drifted copy no-ops and ships advertising the previous version.

Port them into internal/versioncheck so the shell-free checker enforces the
same set:

- source gains an optional expected() so a surface can derive its required
  value; the Windows PE numeric fields must be purely numeric and so carry the
  prerelease-stripped form, and manifest.xml carries the four-part form.
- readWinresVersionField reads the nested RT_VERSION resource path through the
  existing duplicate-key-checked JSON helpers.
- readManifestAssemblyVersion anchors on line start, since the XML declaration
  also carries a version attribute.

Also regenerate the Bazel BUILD files (make bazel-sync). cmd/bd/BUILD.bazel
enumerates srcs explicitly, so the PR's new preflight_versions.go was missing
from it and //cmd/bd:bd_lib failed to compile with `undefined:
runBeadsVersionSyncCheck`; gazelle adds that src, the //internal/versioncheck
dep edge, and BUILD files for the two new packages.

Known follow-up for review: the PR's TestRepositoryReleaseVersionsMatch and
TestPrePushHookOrdinaryPushWorksWithSystemBash read repository files directly,
so they need `data` runfiles to pass under `bazel test` (advisory lane only).

* fix(versioncheck): stop the release gate over-claiming docs coverage; distinguish --expect mismatch

Maintainer review fixup for iteration 1 (both findings minor, non-gating;
scorecard 915/850 approve with Required Changes: None).

Contract & Interface Fidelity (claude + codex): the success line claimed
"Version files and released-docs policy pass" while the checker reads no
documentation surface, and it replaced the shell predecessor's explicit
disclaimer that the docs release line and docs/cli-docs.pin are manual
release steps. Restore the base wording ("Version files in sync at: <v>")
plus the disclaimer, and update the three pins in main_test.go.

This also repairs a consumer neither review lane censused: the tracked
release runbook .beads/formulas/beads-release.formula.toml:475 instructs the
operator that the gate "must print `✓ Version files in sync at: <version>`
before you continue" — the renamed string had silently broken that
acceptance check. Grepping the new spelling finds nothing; the breakage only
shows up when grepping the old one.

Error Handling & Resilience (codex): --expect mismatch reused exit 1, so
.githooks/pre-push answered a tag/checkout mismatch with the version-drift
remedy ("Fix with: scripts/update-versions.sh <version>") — advice that
would rewrite every release surface to the wrong version. Give that case
status 3 and add the matching hook branch pointing at CONTRIBUTING's actual
rule. Only two --expect call sites exist: release.yml:45 (bare non-zero
check, unaffected) and this hook.

Verified at this head: check-versions.sh rc=0 (24 green rows, all three
ported base gates); exit taxonomy 0/2/3 as documented; go test
./internal/versioncheck/ ./scripts/check-versions/ PASS=65 FAIL=0 SKIP=0;
cmd/bd TestTrackedManagedHookSectionsMatchGenerator ok (hook edit sits above
the generator-managed markers); gofmt/vet clean. Both fixes proven
non-vacuous by mutating each back and requiring red.

Declined as out of cleanup scope, recorded for follow-up: making
TestRepositoryReleaseVersionsMatch fixture-based (redesigns the PR's own
test architecture and interacts with the deliberate untracked-discovery pin
at check_test.go:174; harm measured local-only) and declaring bazel data
runfiles (gate impact none — no BAZEL key in either CI_GATE_REQUIRED map at
this base; the remedy needs root filegroups that touch
scripts/bazel_policy_test.go invariants).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(versioncheck): declare the release-gate tests' repo inputs as Bazel data

Base commit e1b2e79484 (#6941) promoted the seven BAZEL* lanes into pr.yml's
CI_GATE_REQUIRED after this branch's merge point, so the two packages this PR
adds are now graded by a required check. Both reach real repository files
through a hand-rolled filepath.Join("..", ".."), which resolves outside the
runfiles tree, and `bazel test //...` failed on them:

  TestRepositoryReleaseVersionsMatch
    open ../../cmd/bd/version.go: no such file or directory
  TestPrePushHookOrdinaryPushWorksWithSystemBash
    runfiles .githooks/pre-push: No such file or directory

Resolve the root through internal/testutil/bazeltest.RepoRoot, the base's
helper for exactly this, which reduces to the previous behavior under plain
`go test`; and declare the inputs as data through a //:release_metadata_files
filegroup aggregating the surfaces versioncheck.releaseSources gates, the
canonical version it compares them against, the uv.lock pin and the tracked
hooks, exported from the packages that own them. The filegroup is hand-listed
because releaseSources is itself a closed list: a newly gated surface must be
added there too, and until it is the test fails under Bazel.

The shell entrypoint's exit-status subtests build the checker from source at
the repository root, which cannot work against a runfiles tree that has no
go.mod, so they skip under Bazel and keep running under `go test`. The guard
sits inside each subtest, not above the loop, so the ordinary-push assertion
still reports as run rather than hiding behind a skip.

Validation: `go test ./internal/versioncheck/ ./scripts/check-versions/` is
unchanged at 65 pass / 0 skip, with all three entrypoint subtests still
executing; both targets pass `bazel test --config=ci`; //scripts:scripts_test
(the tag-taxonomy and Bazel policy tests) passes; `bazel build //...` is clean
across 321 targets; `make bazel-sync` reports no drift and is idempotent.

* test(versioncheck): stop declaring the bazelignored npm manifest as Bazel data

The required `Bazel / test` lane failed on the refreshed head in fork-PR CI:

  TestRepositoryReleaseVersionsMatch
    npm package.json: open .../versioncheck_test.runfiles/_main/
    npm-package/package.json: no such file or directory (expected 1.3.0)

npm-package/ is in .bazelignore (#6798), so Bazel never links it into the
execroot, and a local sandbox cannot stage npm-package/package.json even
though //:release_metadata_files named it and analysis accepted the label.
It resolved only under remote execution, where the client uploads the file
from the workspace. That is how the previous fixup's `bazel test
--config=ci` passed on a host whose bazelrc defaults to remote execution.
Fork PRs get no remote-execution secrets, so CI runs the test in
processwrapper-sandbox, where it fails.

Drop the entry from the filegroup. Under Bazel only, let
TestRepositoryReleaseVersionsMatch tolerate exactly that surface's absence:
the file must be missing, and every other gated surface, the uv.lock pin and
the hook markers must pass. The test logs the gap. This mirrors the base's
skipReleaseFormulaUnderBazel for the bazelignored .beads/. `go test`, which
sees the real checkout, still checks the npm manifest.

Validation: forcing local execution the way fork CI runs (`bazel test
--config=ci --nocache_test_results --remote_executor=
--strategy=TestRunner=processwrapper-sandbox`) reproduced the failure before
the change. After it, //internal/versioncheck:versioncheck_test,
//scripts/check-versions:check-versions_test and //scripts:scripts_test pass
(3 of 3 executed), and both release-gate targets also pass under remote
execution. Drifting a declared surface still fails the sandboxed run. The
tolerance was probed through TEST_SRCDIR and BEADS_TEST_REPO_ROOT: each of
these still fails:
- another drifted surface
- a present but mismatched npm manifest
- an unreadable canonical version
- plain `go test` with the manifest missing

`go test ./internal/versioncheck/ ./scripts/check-versions/`, golangci-lint
and `make bazel-sync-check` are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-10-01 07:46:37 -07:00
ecuthiell
80b13798dc
docs(lint): align contributor guidance with CI (saa-90w) (#5317)
Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell
2026-08-07 05:37:12 -07:00
Julian Knutsen
e9a12ed3b1
docs(test): make TESTING.md canonical (bd-mrs20) (#5226)
Consolidate test execution and design guidance around the smallest trustworthy seam, narrow doubles, semantic versus persistence conformance, strict E2E admission, and proportional verification. Convert the former philosophy documents to compatibility pointers.

Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot

Co-authored-by: CI Bot <ci@beads.test>
2026-08-01 02:30:21 -07:00
Jim Wordelman
a9a48d6e36
test(cli,storage): BEADS_MAX_ROWS behavioral + opt-out gate tests (be-x42v) (#4160)
* feat(storage): be-x42v.1 BEADS_MAX_ROWS defensive cap foundation

Add IssueFilter.MaxRows + IssueFilter.MaxRowsSource and a typed
issueops.ErrTooManyRows error. searchTableInTx routes its LIMIT through
EffectiveSearchLimit (LIMIT MaxRows+1 when MaxRows>0, with Limit
preserved otherwise); SearchIssuesInTx checks EnforceMaxRowsCap after
the issues+wisps merge so the cap reflects the count returned to the
caller. Both helpers are exported so future PG-backend support can
reuse the same logic.

Default MaxRows=0 disables the cap and is byte-identical to today at
every existing call site. Limit semantics are unchanged: Limit=0 still
means unlimited at the contract level.

PG backend is not on origin/main yet; PG cap support is a follow-up
when the postgres backend merges. Validator's per-backend bead exercises
the issueops path via Dolt/embedded fixtures.

Refs: be-x42v (designer §3/§6.2), be-jp5s (architecture D1/R-03).

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

* feat(cli): be-x42v.2 wire --max-rows / BEADS_MAX_ROWS on CLI surface

Adds cmd/bd/max_rows.go with three helpers: addMaxRowsFlag registers
--max-rows int with the designer's spec help text, resolveMaxRows
picks flag > env > 0 (negative flag → exit 1, bad env → warn-and-ignore),
and handleMaxRowsError pattern-matches *issueops.ErrTooManyRows to
emit the two-line stderr message and exit 2 with stdout empty.

The flag is wired on bd list, bd ready, bd dep tree, bd find-duplicates,
and bd graph (designer §4). The env-only resolveMaxRowsEnvOnly variant
is wired on bd lint and the SearchIssues paths inside bd doctor
(conventions + pollution checks). bd cleanup, bd gc, bd export,
bd export --auto, bd migrate-issues, and bd jira explicitly set
MaxRows=0 / MaxRowsSource="" in code so a misconfigured env can't
abort a data-integrity sweep partway through.

bd ready needed storage-layer support too: WorkFilter gains MaxRows +
MaxRowsSource and GetReadyWorkInTx routes its LIMIT through
EffectiveSearchLimit and enforces the cap via EnforceMaxRowsCap on
the row count returned to the caller. bd dep tree applies the cap at
the CLI layer on the TreeNode count since the tree walk doesn't go
through IssueFilter.

bd config show gains a standalone-env collector so BEADS_MAX_ROWS
shows up alongside BEADS_DIR etc. when set. The Viper-managed env
detection skips it because BEADS_MAX_ROWS isn't bound to a config key.

Adds a CONTRIBUTING.md section documenting the opt-out rule for new
IssueFilter sites that aren't on designer §4's wired-up list, with a
pointer to the validator's opt-out test gates (be-x42v.4).

Smoke-tested against the rig database (298 issues):
- bd list --max-rows 5 → exit 2, "--max-rows=5"
- BEADS_MAX_ROWS=5 bd list → exit 2, "BEADS_MAX_ROWS=5"
- BEADS_MAX_ROWS=banana bd list --limit 3 → warn + exit 0
- BEADS_MAX_ROWS=5 bd list --max-rows 0 --limit 3 → exit 0
- bd list --max-rows -1 → exit 1, "must be non-negative"
- bd ready --max-rows 5 → exit 2 (storage layer fires)
- bd dep tree be-jp5s --max-rows 1 → exit 2 (CLI-layer count)
- bd find-duplicates --max-rows 5 → exit 2
- bd graph --all --max-rows 5 → exit 2
- BEADS_MAX_ROWS=5 bd lint → exit 2 (env-only)
- BEADS_MAX_ROWS=5 bd export → exit 0, 299 lines (opt-out)
- BEADS_MAX_ROWS=10 bd config show → lists BEADS_MAX_ROWS

The 10 CLI behavioral test scenarios for bd list are owned by
be-x42v.3 (validator). Coverage for the non-list paths, the env-only
doctor family, and config show is filed as be-u8z9 (needs-tests,
routed to validator).

Refs: be-x42v (designer §2-§5), be-x42v.1 (foundation).

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

* chore: release gate PASS for be-x42v.1 + be-x42v.2 (BEADS_MAX_ROWS)

Documents PASS evaluation across the six gate criteria for the
storage foundation (be-x42v.1, 3900c1bdc) and the CLI wiring
(be-x42v.2, dea537c56) shipping together. Review verdicts: be-xf0o
(foundation) and be-2p12 (CLI), both PASS from Opus 4.7 reviewer.

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

* docs: regenerate CLI reference for --max-rows flag

* docs: revert federation to pure-go stub in CLI_REFERENCE.md

CI's check-doc-flags freshness check runs generate-cli-docs.sh with
CGO_ENABLED=0. The previous regeneration used a CGO binary, expanding
the federation section with subcommands. Revert to the requires-CGO
stub that the pure-go binary produces.

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

* docs: revert website federation.md pages to pure-go stub (be-x42v)

Three website cli-reference/federation.md files still had CGO-enabled
content after CLI_REFERENCE.md was reverted. This commit brings them
into sync with the pure-go stub, resolving the Check doc flags freshness
CI failure on PR #3908.

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

* test(cli): be-u8z9 BEADS_MAX_ROWS non-list command paths + config show

Locks down the manually-verified behavior shipped in be-x42v.2 across the
CLI surface beyond `bd list`.

cmd/bd/max_rows_test.go (new):
  - ReadyMaxRows_FlagOverCap_Exits2  - bd ready --max-rows N → exit 2
  - ReadyMaxRows_EnvOverCap_Exits2   - BEADS_MAX_ROWS=N bd ready → exit 2
  - DepTreeMaxRows_TreeNodes_Exits2  - tree-node count cap in dep tree
  - FindDuplicatesMaxRows_Exits2     - find-duplicates --max-rows N
  - GraphAllMaxRows_Exits2           - graph --all --max-rows N
  - LintMaxRows_EnvOnly_Exits2       - bd lint with BEADS_MAX_ROWS=N
  - LintMaxRows_NoFlagAccepted       - cobra rejects --max-rows on lint
  - ConfigShow_ListsBeadsMaxRows     - bd config show surfaces the env var
  - ConventionsMaxRows_EnvOnly       - skipped (bd doctor needs server mode,
                                       follow-up filed as be-pc8c)
  - PollutionMaxRows_EnvOnly         - skipped (same reason)

cmd/bd/ready_max_rows_test.go (new):
  - TestGetReadyWork_MaxRowsSuite — exercises WorkFilter.MaxRows in
    GetReadyWork (under cap / over cap / zero disabled / with Limit
    matrix), via newTestStore. Companion to the SearchIssues parity
    work in be-x42v.3.

Refs: be-u8z9 (this bead), be-x42v.2 (builder), be-pc8c (follow-up).

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

* test(cli,storage): be-x42v.3 BEADS_MAX_ROWS bd list scenarios + backend parity

Covers the 10 CLI scenarios from designer §6.1 against `bd list` and the
5 storage scenarios from designer §6.2 against both Dolt-server and
embedded backends.

cmd/bd/max_rows_test.go (extended):
  TestEmbeddedMaxRowsList — 10 subtests on a shared 21-issue rig:
    - Disabled_NoEnv             (baseline, no cap)
    - Flag_UnderCap              (--max-rows 100 over 21 rows → success)
    - Flag_OverCap               (--max-rows 5 → exit 2, source attribution, empty stdout)
    - Env_OverCap                (BEADS_MAX_ROWS=5 → exit 2, env source)
    - Flag_OverridesEnv          (env=5 flag=100 → success)
    - Flag_Zero_OverridesEnv     (env=5 --max-rows 0 → success, explicit disable)
    - BadEnv_LogsAndIgnores      (env=banana → warning + normal output, exit 0)
    - Negative_FlagRejected      (--max-rows -1 → "must be non-negative", exit 1)
    - LimitSet_CapTighter        (--limit 100 --max-rows 5 → exit 2)
    - LimitSet_CapLooser         (--limit 5 --max-rows 100 → 5 rows, exit 0)

internal/storage/embeddeddolt/search_max_rows_test.go (new):
  TestSearchIssues_MaxRows_{NotExceeded,Exceeded,Zero_NoCap,WithLimit}
  Exercises SearchIssues end-to-end against the embedded backend on a
  6-row fixture, including the four-quadrant (Limit, MaxRows) matrix.

internal/storage/dolt/search_max_rows_test.go (new):
  Identical scenarios against the dolt-server backend. Per-backend
  parity is implicit: both SearchIssues entry points wrap
  issueops.SearchIssuesInTx, so cap behavior is shared by construction.
  Same fixture + same assertions ensures divergence cannot ship silently.

PG backend coverage is deferred until the postgres-backend branch lands
(per PR #3908 description and parent designer notes).

Refs: be-x42v.3 (this bead), be-x42v.2 (builder), be-u8z9 (sibling validator for non-list paths).

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

* test(cli): be-x42v.4 opt-out gate tests for data-integrity commands

Add filterCapturingStore spy and four MaxRows=0 gate tests asserting
that bd export, bd export --auto, bd jira sync, and bd migrate-issues
always construct IssueFilter with MaxRows=0 / MaxRowsSource="" per
designer §4.1 opt-out rule. A BEADS_MAX_ROWS env var on these paths
would corrupt backups, sync state, or migration runs mid-flight.

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

* test(cli): be-x42v.4 add TestExport_BypassesBeadsMaxRows behavioral gate

End-to-end belt-and-suspenders test (designer §6.4): sets BEADS_MAX_ROWS=1,
seeds 5 task issues, runs runExport, and asserts 5 JSONL lines in the output.
Completes the be-x42v.4 acceptance criteria for the bypass behavioral test
alongside the filter-spy gate already committed.

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

* test(cli): be-pc8c server-mode BEADS_MAX_ROWS gate for bd doctor --check={conventions,pollution}

TestDoctorConventionsMaxRows_EnvOnly_Exits2 and TestDoctorPollutionMaxRows_EnvOnly_Exits2
cover the two subtests that were skipped in max_rows_test.go because bd doctor refuses
to run in embedded mode (doctor.go:188). Both tests seed 6 open issues against the
Dolt test server with BEADS_MAX_ROWS=3, assert exit 2, and confirm BEADS_MAX_ROWS=3
in the combined output.

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

* fix(search): enforce MaxRows cap when wisps table is empty

SearchIssuesInTx skipped EnforceMaxRowsCap on the common empty-wisps
path: when filter.Ephemeral is nil/false and the wisps table is empty,
the early `return results, nil` returned before the post-merge cap check.
The issues-only result set (LIMIT cap+1) could exceed MaxRows yet never
trip ErrTooManyRows. Enforce the cap before the early return.

Fixes TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows and
TestSearchIssues_MaxRows_WithLimit (internal/storage/embeddeddolt).

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

* fix(rebase): re-home BEADS_MAX_ROWS enforcement onto post-rebase seams

Fixes gaps exposed by rebasing PR #4160 onto current upstream/main,
found by actually running the PR's own gate tests rather than just
resolving textual conflicts:

- internal/storage/issueops/search.go: the Q2 perf-escape-hatch
  SkipWisps early return (added by main's search perf work, landed
  after this PR's original design) skipped EnforceMaxRowsCap entirely.
  bd list sets SkipWisps=true by default, so `bd list --max-rows N`
  silently ignored the cap. Enforce the cap on that return path too,
  mirroring the existing empty-wisps-table fix alongside it.

- internal/storage/issueops/search_counts.go: SearchIssuesWithCountsInTx
  (the `--json` query path, already present at the PR's merge-base but
  never wired for MaxRows by the original be-x42v.1/.2 commits) neither
  sized its SQL LIMIT off the cap nor enforced it on the merged result.
  Thread filter.MaxRows through EffectiveSearchLimit for the query LIMIT
  and check EnforceMaxRowsCap in the shared finishSearchIssuesWithCounts
  terminal helper (now returns an error), which every exit path already
  routed through. Fixes be-x42v.3's TestEmbeddedMaxRowsList/Flag_OverCap
  (`bd list --json --max-rows 5`), which failed after the rebase.

- cmd/bd/jira_max_rows_gate_test.go,
  cmd/bd/migrate_issues_max_rows_gate_test.go: seed INSERTs predate
  migration 0049 (LONGTEXT NOT NULL on issues.description/design/
  acceptance_criteria/notes, no default) that landed on main after
  this branch's merge-base. Provide empty-string values for the
  now-required columns.

Not fixed (separate, pre-existing gap; no gate test in this PR
exercises it): GetReadyWorkWithCountsInTx (`bd ready --json` /
`bd list --ready --json`) also doesn't thread MaxRows. Left alone to
keep this rebase to conflict resolution rather than expanding scope;
worth a follow-up bead.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address adjudicated cross-vendor review follow-up (be-x42v.4)

Works the MUST-FIX / SHOULD-FIX list from the adjudicated claude-opus +
codex-gpt-5.6-sol review on the rebase (25e35cc3e), landing coverage gaps
the vendors found in the feature's own promise rather than the rebase
mechanics.

MUST-FIX:

1. internal/storage/issueops/claim.go: ClaimReadyIssueInTx forwarded the
   caller's MaxRows/MaxRowsSource into its internal unbounded
   GetReadyWorkInTx scan, so a rig-wide cap (e.g. BEADS_MAX_ROWS=100 with
   150 ready issues) hard-failed a claim that only ever consumes one row.
   Bound the internal scan via Limit instead, then clear the cap fields.

2. cmd/bd/ready.go, internal/storage/issueops/ready_work_counts.go:
   GetReadyWorkWithCountsInTx (ready --json / list --ready --json) never
   enforced MaxRows at all — a pre-existing gap in the original PR (the
   function predates this branch's merge-base), not something the rebase
   introduced. Threaded EffectiveSearchLimit into its query LIMIT and added
   EnforceMaxRowsCap via a new finishReadyWorkWithCounts terminal helper,
   mirroring finishSearchIssuesWithCounts. Wired handleMaxRowsError on the
   bd ready --json error branch.

3. cmd/bd/max_rows.go + list/ready/graph/dep/find-duplicates: proxied-server
   mode silently ignored the cap (the proxied repository doesn't thread
   MaxRows through the UOW pipeline). Added rejectMaxRowsUnderProxiedServer,
   called on every command that registers --max-rows before it diverts to
   its *ProxiedServer path — an explicit --max-rows or BEADS_MAX_ROWS now
   errors out under --proxied-server instead of no-oping.

4. cmd/bd/list.go: `--limit N --max-rows N` errored instead of truncating.
   withFetchOneExtra unconditionally bumped Limit to N+1 for its own
   >N-matches truncation-hint probe, which then crossed EffectiveSearchLimit's
   `limit > maxRows` branch and tripped the cap on the probe row alone, even
   though the delivered set is always trimmed back to N. withFetchOneExtra
   now skips the bump when MaxRows is active and no looser than Limit;
   >N-matches semantics for limit<maxRows are unaffected.

5. cmd/bd/list.go: `bd list --watch` swallowed the initial-query cap error
   (logged to stderr, returned void, exited 0). watchIssues now returns the
   initial-query error instead of handling it itself; runListCore routes it
   through handleMaxRowsError for exit-code-2 semantics. Mid-poll refresh
   failures still just log and continue (interactive command, not a reason
   to kill the watch loop).

6. cmd/bd/max_rows.go + every call site: handleMaxRowsError and the
   --max-rows usage-error path in resolveMaxRows called os.Exit directly
   from deep inside RunE, bypassing both the command's own metrics defer
   and main()'s post-ExecuteC metrics.CloseAndFlush(). Converted both to
   return errors: resolveMaxRows now returns (int, string, error) and
   handleMaxRowsError returns error, both following the exact &exitError{Code:
   N}-via-RunE precedent already used elsewhere in this package (e.g.
   list_input.go's skip-labels-conflict check, HandleErrorRespectJSON).
   doctor_conventions.go's runConventionsLint (called from a "()
   []doctorCheck" advisory-checks aggregator with no error channel) needed
   its own (([]doctorCheck, error) signature to propagate the one non-advisory
   failure mode; every other call site was already RunE-adjacent.

SHOULD-FIX (both mechanical, done):

7. cmd/bd/graph.go: `bd graph <issue>` (no --all) never resolved the cap.
   loadGraphSubgraph is a BFS over per-ID GetDependents/GetDependencies
   lookups with no IssueFilter to thread MaxRows through, so — mirroring
   dep tree — the cap is now checked post-hoc against the final
   connected-component node count. Documented both graph's per-status
   (--all) and post-hoc (single-issue) cap semantics, and dep tree's
   post-hoc semantics, in their flag help text.

8. internal/storage/issueops/ready_work.go: getReadyWispsInTx's unbounded
   (Limit<=0) branch queried and hydrated the *entire* wisps table before
   the post-merge cap check in GetReadyWorkInTx ever ran, defeating the
   "circuit breaker against pathological queries" purpose for
   --include-ephemeral. readyWorkWispIssueFilter now propagates
   MaxRows/MaxRowsSource so EffectiveSearchLimit bounds that query to
   cap+1 up front.

Tests added: TestClaimReadyIssue_MaxRows_LargePoolUnderLowCap (1),
ReadyMaxRowsJSON_FlagOverCap_Exits2 + ListReadyMaxRowsJSON_FlagOverCap_Exits2
(2), reject_max_rows_flag + reject_max_rows_env + allow_max_rows_zero under
TestProxiedServerList (3), LimitEqualsCap_TruncatesNotErrors +
LimitEqualsCap_JSON_TruncatesNotErrors (4), Watch_FlagOverCap_Exits2 (5),
GraphSingleIssueMaxRows_NodeCount_Exits2 + _UnderCap_NoError (7),
ReadyIncludeEphemeralMaxRows_FlagOverCap_Exits2 (8).

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows sweep passes in both dolt-server and
BEADS_TEST_EMBEDDED_DOLT=1 modes (one dolt-testcontainer flake observed and
confirmed non-reproducing on retry, consistent with prior sessions);
TestProxiedServerList passes with BEADS_TEST_PROXIED_SERVER=1.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address round-2 delta review regressions (be-x42v.4 round 3)

opus verified all eight round-2 items as implemented, but codex found three
regressions those fixes introduced, confirmed on adjudication. Common
thread: enforce the cap on the DELIVERED result, not on fetched/merged
intermediates, and don't let the safety rejection block one-row operations.

1. cmd/bd/ready.go: proxied `bd ready --claim` was rejected by
   rejectMaxRowsUnderProxiedServer before it could dispatch to
   runReadyProxiedClaim, even though --claim always delivers exactly one
   row and the direct-path fix (claim.go, round 2) already exempts claim
   from cap enforcement for that exact reason. Moved the claimReady flag
   parse before the proxied branch and exempt --claim from the rejection;
   bulk (non-claim) proxied `bd ready` still rejects an active cap. Added
   claim_succeeds_under_env_max_rows_cap plus
   reject_bulk_ready_under_max_rows_{flag,env} to
   ready_proxied_integration_test.go.

2. internal/storage/issueops/ready_work_counts.go: with --include-ephemeral,
   GetReadyWorkWithCountsInTx's issues and wisps queries are each
   independently bounded by EffectiveSearchLimit(filter.Limit,
   filter.MaxRows), so the merged pre-trim slice can hold up to ~2x that
   per-table bound even when filter.Limit <= filter.MaxRows (e.g. limit=2,
   cap=3, 2 rows/table -> merged 4 -> false "too many rows" even though the
   delivered page, trimmed to 2, is well within the cap). Reordered
   finishReadyWorkWithCounts to trim to Limit before checking the cap,
   mirroring GetReadyWorkInTx's non-counts path (mergeReadyWisps already
   trims before its caller's EnforceMaxRowsCap runs). Verified this
   reproduces "4 found, --max-rows=3 exceeded" on the pre-fix code and is
   fixed after. Added ReadyIncludeEphemeralMaxRowsJSON_MergedUnderLimit_NoError.

3. cmd/bd/list.go: round-2's fix for `--limit N --max-rows N` (skip the
   withFetchOneExtra probe-row bump entirely when Limit>=MaxRows) stopped
   the false cap error but also stopped fetching the extra row, so
   len(results) could never exceed effectiveLimit and the GH#3212
   truncation notice silently stopped firing — a partial result started
   presenting as complete. Restored the probe-row fetch (Limit still bumps
   to N+1) and instead bump MaxRows to N+1 in lockstep, but only in the
   exact Limit==MaxRows case: this keeps the probe row inside the
   (temporarily N+1) cap so EnforceMaxRowsCap doesn't trip on it, while the
   CLI's own len(results)>effectiveLimit check still sees the extra row and
   correctly reports truncated=true. Tighter-cap (Limit>MaxRows) and
   looser-cap (Limit<MaxRows) cases are unaffected — MaxRows is left
   unbumped there, so a genuine violation still reports the true cap value.
   printTruncationHint's text is gated on ui.IsStderrTerminal() and
   unconditionally suppressed for this subprocess test harness's piped
   stderr (matches the existing limit_truncation_hint subtest's documented
   constraint), so the fix is verified via 4 new unit tests asserting
   withFetchOneExtra's exact bump values directly
   (TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe et al.)
   rather than the unobservable hint text; extended
   LimitEqualsCap_TruncatesNotErrors's comment to document this and point
   to the unit tests.

Opus nits:

4. internal/storage/issueops/claim.go: bounding the claim scan at
   Limit=MaxRows (round 2) meant a BEADS_MAX_ROWS=1 rig would only attempt
   the single top-of-queue ready row and return "nothing to claim" if it
   was transiently unclaimable (e.g. a race with another agent), even with
   plenty of other ready work available. Restored the unbounded scan
   (Limit=0); the breaker's job is to bound delivered payloads, and a
   claim's payload is always exactly one row regardless of scan size.

5. cmd/bd/find_duplicates.go: replaced the inlined proxied-server rejection
   check with a call to rejectMaxRowsUnderProxiedServer so the message
   can't drift from the other 4 commands that use it.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra sweep passes in both dolt-server
and BEADS_TEST_EMBEDDED_DOLT=1 modes; TestProxiedServerList +
TestProxiedServerReady (full suites, ~200s) pass with
BEADS_TEST_PROXIED_SERVER=1; broader TestList|TestWatch|TestGraph|
TestDepTree|TestReady|TestClaim|TestFindDuplicates sweep clean except the
same pre-existing unrelated ICU-header build failure noted in the round-2
commit (confirmed via stash-based control test to reproduce identically
without this round's changes).

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address round-3 delta review items (be-x42v.4 round 4)

Converging: four small items adjudicated from round-3 delta reviews.

1. internal/storage/issueops/search.go, search_counts.go: round 3's
   trim-before-cap fix landed in finishReadyWorkWithCounts but not on the
   sibling bd list search paths. `bd list --include-infra --limit 2
   --max-rows 5` (3 durable + 3 wisps) exited 2 in both output modes even
   though the delivered page is 2 rows, since --include-infra disables the
   default SkipWisps escape hatch so the wisps merge actually runs.
   Reproduced live: "6 found, --max-rows=5 exceeded" on the pre-fix code.
   Mirrored the ready remedy: trim to filter.Limit (guarded by Limit>0)
   before EnforceMaxRowsCap in searchInTx's four exit points (added a
   trimToSearchLimit helper) and in finishSearchIssuesWithCounts (swapped
   the cap/trim order). Fixed search_counts.go's doc comment, which still
   asserted the old cap-before-trim rationale and directly contradicted
   ready_work_counts.go's. Single-source results are unaffected (a lone
   query never exceeds Limit when Limit>0, so the trim there is a no-op);
   Limit=0 and genuine Limit>MaxRows overage still error. Added
   IncludeInfraMergedUnderLimit_NoError (both bd list output modes) to
   TestEmbeddedMaxRowsList.

2. cmd/bd/ready.go: the round-3 fix that exempts proxied `ready --claim`
   from rejectMaxRowsUnderProxiedServer also skipped resolveMaxRows
   entirely for that branch, so `--max-rows -1` was silently accepted
   under proxied claim (every other command, direct or proxied, rejects
   it with exit 1). Still call resolveMaxRows in the claim-exempt branch
   for its validation side effect, ignoring the resolved cap for the
   claim itself. Reproduced live (claim succeeded instead of failing) on
   the pre-fix code. Added claim_rejects_invalid_max_rows_flag to
   ready_proxied_integration_test.go.

3. cmd/bd/find_duplicates.go, cmd/bd/max_rows.go: find-duplicates resolved
   --max-rows twice under proxied mode (once to build its filter, again
   inside rejectMaxRowsUnderProxiedServer), doubling the malformed-env
   stderr warning. Split rejectMaxRowsUnderProxiedServer into itself plus
   a new rejectResolvedMaxRowsUnderProxiedServer(maxRows int) that takes
   an already-resolved value; find_duplicates.go now calls the latter with
   its existing resolved maxRows instead of re-resolving.

4. internal/storage/issueops/claim.go: added a comment sentence noting the
   unbounded-scan trade-off per the adjudication note — parity with
   pre-PR main and correctness-first (preserves claim's existing
   fairness/ordering across the ready set); a bounded, paged scan is a
   deliberate follow-up, not folded in here.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra sweep passes in both dolt-server
and BEADS_TEST_EMBEDDED_DOLT=1 modes (including the two new regression
tests); full TestProxiedServerReady suite (~211s) passes with
BEADS_TEST_PROXIED_SERVER=1; internal/storage/issueops unit tests pass;
broader TestList|TestWatch|TestGraph|TestDepTree|TestReady|TestClaim|
TestFindDuplicates sweep clean except the same pre-existing unrelated
ICU-header build failure noted in prior rounds. Both new regression tests
(item 1 and item 2) reproduce the reported failure on the pre-fix code via
git-stash and pass after.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): sort merged issues+wisps before trim in searchInTx (be-x42v.4 round 5)

codex P1, confirmed live: searchInTx's merge branch concatenates two
independently ORDER BY'd legs (`results = append(filtered,
wispResults...)`), and round-4's trimToSearchLimit then sliced that
UNSORTED concatenation. With Limit=N and durable rows alone filling N, a
higher-ranked wisp (per filter.SortBy/SortDesc) was silently dropped from
the page — before round 4 the CLI received the full merged set and its own
sort-then-trim produced correct page membership; round 4 moved a naive
prefix-trim into storage ahead of any global re-sort.

Fix: added a `less func(a, b T, sortBy string, sortDesc bool) bool` field
to searchProjection[T], populated for issueProjection via sqlbuild.Less
(the existing Go-side mirror of the SQL ORDER BY, already used correctly
by search_counts.go's sortSearchIssuesWithCounts). searchInTx's merge
branch now re-sorts the concatenation via a new sortMergedResults helper
before trimToSearchLimit runs, mirroring how finishSearchIssuesWithCounts
already orders before its own trim. idProjection (bare-ID search, no
sortable payload) leaves less nil — sortMergedResults no-ops in that case;
documented why this is safe today (no current caller combines Limit>0 with
a merged, non-SkipWisps ID-only search — see id_parser.go, which always
passes Limit=0) and where to look if that changes. The other three
trimToSearchLimit call sites in searchInTx are single-source (already
SQL-ordered), so they don't need this.

Checked the two round-3/round-4-cited "mirror" precedents per the
adjudication note, since this bug's shape (unsorted-concat-then-trim) could
plausibly recur there: GetReadyWorkInTx's mergeReadyWisps already calls
sortReadyIssues(kept, filter.SortPolicy) before its own Limit trim, and
GetReadyWorkWithCountsInTx / SearchIssuesWithCountsInTx both already sort
(sortIssuesWithCountsByPolicy / sortSearchIssuesWithCounts) before their
finish* trim-then-cap helpers. All three were already globally ordered
before trimming; only searchInTx had the bug.

Added IncludeInfraMerged_WispOutranksDurable_InDeliveredPage to
TestEmbeddedMaxRowsList: 3 durable P2 issues + 1 wisp at P0 (outranks under
the default priority-ASC sort), --limit 1 in both bd list output modes —
asserts the P0 wisp is the delivered row, not an arbitrary P2 durable row.
Reproduces exactly against 77227aa67 (the durable row is returned instead
of the wisp) and passes after the fix.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra + Search sweep passes in both
dolt-server and BEADS_TEST_EMBEDDED_DOLT=1 modes (including the new
regression test); internal/storage/issueops unit tests pass.

Agent-Signature: claude-sonnet-medium on behalf of matt wilkie

* docs: remove --max-rows lines from pinned-generator CLI docs (be-x42v.4 CI fix)

CI's "Check doc flags freshness" job compares docs/CLI_REFERENCE.md and
docs/cli-reference/*.md against bd built from the pin in
docs/cli-docs.pin (v1.1.0), which predates --max-rows/BEADS_MAX_ROWS —
the same pinned-doc-generator trap that hit PRs 3920 and 4022 in this
sweep. Any doc lines this PR added for the new flag are flagged stale
against that older pinned build, and the failure cascades into "PR
Policy (wrapper timing)" via make ci-pr-policy.

Applied CI's own generated fix verbatim (downloaded the
cli-docs-freshness-patch artifact from the failing job
https://github.com/gastownhall/beads/actions/runs/30067827283/job/89403539322,
git apply --check passed cleanly, applied as-is — no manual edits).
Removes the six --max-rows generated-doc lines (bd list, bd ready, bd dep
tree, bd find-duplicates, bd graph — CLI_REFERENCE.md and the matching
cli-reference/*.md) plus the incidental column-width realignment in the
bd graph flag tables that removing the widest flag name triggers.

The flag help strings themselves (cmd/bd/max_rows.go's addMaxRowsFlag)
are untouched — those are the source of truth for docs generation and
will regenerate correctly once docs/cli-docs.pin advances past this
PR's merge. This is a pinned-generator artifact of the CI pipeline, not
a statement that the flag is undocumented.

Agent-Signature: claude-sonnet-medium on behalf of maphew

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-24 01:40:36 -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
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
Harry Miller
9ca6b51b47
ci(nix): auto-update default.nix vendorHash on dependabot Go bumps (#3804)
* chore: track workflow formulas for portability

Force-add gh-issue-to-pr and gh-pr-review formulas so they can be
cloned to new machines. These live in .beads/formulas/ which is
normally gitignored, but formulas are code (not database state).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore: untrack workflow formulas

Remove gh-issue-to-pr and gh-pr-review formulas from git tracking.
These are already covered by .gitignore (.beads/) and shouldn't be
sent upstream.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* ci(nix): auto-update vendorHash for dependabot Go bumps (beads-bz5)

Dependabot Go-module bumps consistently fail the `nix build .#default`
CI gate because default.nix has a hardcoded vendorHash that any
go.mod/go.sum change invalidates. PRs sit stuck for days (#3468, #3637,
#3638 currently affected) until a maintainer manually computes the new
hash. This workflow detects the drift, runs the existing
scripts/update-nix-vendorhash.sh, and pushes the hash bump back to the
dependabot branch.

Uses pull_request_target because GITHUB_TOKEN is read-only on
pull_request workflows triggered by dependabot. Safety guards: only
runs when actor and PR user are both dependabot[bot] AND the PR head
is on the upstream repo (dependabot never opens PRs from forks).

Caveat documented in CONTRIBUTING.md: GitHub does not retrigger
pull_request workflows on GITHUB_TOKEN-authored commits, so a
maintainer may need to re-run nix-build once after the auto-fix push.
The workflow's own success serves as the green signal that the hash
is correct.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 15:36:16 -07:00
matt wilkie
7044802d65
Document project scope boundaries (mybd-1fn) (#3842) 2026-05-13 06:49:11 -07:00
seanmartinsmith
d07112bde7
docs: add lightweight PR description template (#3750)
adds .github/PULL_REQUEST_TEMPLATE.md with three short sections (What /
Why / Verification) and references it from CONTRIBUTING.md's Pull
Request Hygiene list.

scaffolding only - no checkboxes, no required fields, no enforcement.
contributors can replace or delete sections freely. helps reviewers
(human or agent) parse intent before diving into the diff and gives
AI-generated PRs a predictable shape to fill.

Fixes #3748
2026-05-06 12:32:16 -07:00
matt wilkie
46be5594d6
Add maintainer PR guidelines (bd-k0j) (#3665)
Turn the PR assessment workflow from @steveyegge 's Vibe Maintainer into an agent-neutral maintainer PR guidelines documents
2026-05-02 13:21:15 -07:00
Kevin Glynn
8b2f21745f
docs: fix stale agent instructions across 5 files (#3436)
Fix stale agent-facing documentation for Dolt-only storage, build/test commands, claiming work, and removed references. Includes maintainer cleanup to align remaining stale test guidance with the current make test / test-icu-path policy.\n\nCo-authored-by: Kevin Glynn <12972584+kevglynn@users.noreply.github.com>\nCo-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-25 11:45:39 -07:00
matt wilkie
6e506b6ddd
Add PR preflight and contributor intake guidance (#3470)
* Handle legacy PR status contexts

* docs: add contributor PR intake checklist

* docs: wire PR preflight into agent guidance
2026-04-24 15:44:06 -07:00
Ben Madore
3b39ce577a
docs: update user-facing URLs from steveyegge/beads to gastownhall/beads
Co-authored-by: Ben Madore <823868+madorb@users.noreply.github.com>
2026-04-24 08:17:42 -07:00
matt wilkie
b90ee4cf4c
ci: add nix build check to catch vendorHash drift (GH#3298) (#3364)
Adds a CI job that runs `nix build .#default` on PRs touching go.mod,
go.sum, default.nix, flake.nix, or flake.lock, so dependabot bumps
that invalidate vendorHash fail loudly in CI instead of silently
breaking Nix users on main (as happened in GH#3221).

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-20 13:21:53 -07:00
matt wilkie
a315ffd4d3
docs: add ICU regex policy and update build deps (GH-3126)
docs: add ICU regex policy and update build deps (GH-3126)
2026-04-10 11:38:05 -07:00
matt wilkie
0ed8d0b271
docs: add contributor protection policy for AI agents (#3151)
Prevents agents from silently overwriting external contributor PRs.
Prompted by PR #3143 where bgjackma's work was reimplemented without
attribution.

- CONTRIBUTING.md: "Your PR Will Not Be Overwritten" section
- AGENT_INSTRUCTIONS.md: check-before-you-build procedure + CONTRIBUTING.md reference
- AGENTS.md: cross-reference to contributor protection
2026-04-09 12:41:43 -07:00
matt wilkie
d919e1aabe docs: add ICU regex policy and update build dependency guidance (GH-3126)
Add docs/ICU-POLICY.md as the authoritative reference for how ICU is
handled across all platforms. Update CONTRIBUTING.md and INSTALLING.md
to stop listing ICU as a build requirement (it's test-only since all
builds use gms_pure_go).

Resolves confusion from overlapping PRs (#2991, #3066, #3112) where
agents and contributors were doing/undoing each other's ICU fixes
without a written policy.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 20:24:05 -07:00
Harry Miller
34a399bc9c
docs: remove dead dual-mode test framework references from CONTRIBUTING.md (#2958)
The dual-mode test framework (RunDualModeTest/DualModeTestEnv) was
deleted when the daemon/RPC layer was removed. Replace with
documentation of current testing patterns:

- CGO vs non-CGO test split and how to run each
- Test isolation with t.TempDir() and test helpers
- Table-driven test example

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-02 19:18:48 -07:00
Amp
47bcd0f44e docs: add PR hygiene and ZFC sections to CONTRIBUTING.md
- Add explicit 'one issue per PR, one PR per issue' rule
- Warn against including .beads/ data or unrelated changes
- Add ZFC section with link to Yegge's blog post

Amp-Thread-ID: https://ampcode.com/threads/T-019d20ed-0faa-762f-81dd-08f523c25ca2
Co-authored-by: Amp <amp@ampcode.com>
2026-03-24 10:43:41 -07:00
beads/crew/elinor
90da8f6028 docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4)
Replace JSONL storage/sync references with Dolt-native equivalents across
documentation, plugin resources, website docs, agent instructions, and
example READMEs. Preserves legitimate JSONL references (bd import/export
commands, CHANGELOG history, routes.jsonl/interactions.jsonl concepts).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 22:18:02 -08:00
topaz
062aedbed7 docs: remove stale daemon references from all documentation (GH#1982)
Sweep 65 markdown files across docs/, website/, claude-plugin/, examples/,
integrations/, and root to replace removed `bd daemon` references with
current Dolt server mode equivalents. CHANGELOG.md preserved per policy.

Key replacements:
- `bd daemon start/stop/status` → `bd dolt start/stop` / `bd doctor`
- `bd daemons killall/health/logs` → `bd dolt stop` / `bd doctor`
- `--no-daemon` flag → removed (embedded mode is default)
- `BEADS_NO_DAEMON` / `BEADS_DAEMON_MODE` env vars → removed
- `.beads/bd.sock` → removed
- "daemon mode" / "direct mode" → "server mode" / "embedded mode"
- daemon.pid/daemon.log → .beads/dolt/sql-server.pid/.log

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

Executed-By: beads/polecats/topaz
Rig: beads
Role: polecats
2026-02-22 17:57:53 -08:00
emma
1feee20e95 docs: update stale sqlite references to dolt in key contributor docs
- CONTRIBUTING.md: update directory layout, test commands, database
  inspection, and dual-mode description to reference Dolt
- BENCHMARKS.md: update all benchmark commands from sqlite to dolt paths
- docs/ARCHITECTURE.md: update storage implementation table entry
- docs/CLAUDE.md: remove references to deleted sqlite/ and memory/
  storage backends

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

Executed-By: beads/crew/emma
Rig: beads
Role: crew
2026-02-16 00:56:29 -08:00
Joseph Turian
6ab2e294f1 docs: add Docker trick for updating flake.lock without nix
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 21:54:03 -05:00
Ryan
ffe0dca2a3
feat(daemon): unify auto-sync config for simpler agent workflows (#904)
* feat(daemon): unify auto-sync config for simpler agent workflows

## Problem

Agents running `bd sync` at session end caused delays in the Claude Code
"event loop", slowing development. The daemon was already auto-exporting
DB→JSONL instantly, but auto-commit and auto-push weren't enabled by
default when sync-branch was configured - requiring manual `bd sync`.

Additionally, having three separate config options (auto-commit, auto-push,
auto-pull) was confusing and could get out of sync.

## Solution

Simplify to two intuitive sync modes:

1. **Read/Write Mode** (`daemon.auto-sync: true` or `BEADS_AUTO_SYNC=true`)
   - Enables auto-commit + auto-push + auto-pull
   - Full bidirectional sync - eliminates need for manual `bd sync`
   - Default when sync-branch is configured

2. **Read-Only Mode** (`daemon.auto-pull: true` or `BEADS_AUTO_PULL=true`)
   - Only receives updates from team
   - Does NOT auto-publish changes
   - Useful for experimental work or manual review before sharing

## Benefits

- **Faster agent workflows**: No more `bd sync` delays at session end
- **Simpler config**: Two modes instead of three separate toggles
- **Backward compatible**: Legacy auto_commit/auto_push settings still work
  (treated as auto-sync=true)
- **Adaptive `bd prime`**: Session close protocol adapts when daemon is
  auto-syncing (shows simplified 4-step git workflow, no `bd sync`)
- **Doctor warnings**: `bd doctor` warns about deprecated legacy config

## Changes

- cmd/bd/daemon.go: Add loadDaemonAutoSettings() with unified config logic
- cmd/bd/doctor.go: Add CheckLegacyDaemonConfig call
- cmd/bd/doctor/daemon.go: Add CheckDaemonAutoSync, CheckLegacyDaemonConfig
- cmd/bd/init_team.go: Use daemon.auto-sync in team wizard
- cmd/bd/prime.go: Detect daemon auto-sync, adapt session close protocol
- cmd/bd/prime_test.go: Add stubIsDaemonAutoSyncing for testing

* docs: add comprehensive daemon technical analysis

Add daemon-summary.md documenting the beads daemon architecture,
memory analysis (explaining the 30-35MB footprint), platform support
comparison, historical problems and fixes, and architectural guidance
for other projects implementing similar daemon patterns.

Key sections:
- Architecture deep dive with component diagrams
- Memory breakdown (SQLite WASM runtime is the main contributor)
- Platform support matrix (macOS/Linux full, Windows partial)
- Historical bugs and their fixes with reusable patterns
- Analysis of daemon usefulness without database (verdict: low value)
- Expert-reviewed improvement proposals (3 recommended, 3 skipped)
- Technical design patterns for other implementations

* feat: add cross-platform CI matrix and dual-mode test framework

Cross-Platform CI:
- Add Windows, macOS, Linux matrix to catch platform-specific bugs
- Linux: full tests with race detector and coverage
- macOS: full tests with race detector
- Windows: full tests without race detector (performance)
- Catches bugs like GH#880 (macOS path casing) and GH#387 (Windows daemon)

Dual-Mode Test Framework (cmd/bd/dual_mode_test.go):
- Runs tests in both direct mode and daemon mode
- Prevents recurring bug pattern (GH#719, GH#751, bd-fu83)
- Provides DualModeTestEnv with helper methods for common operations
- Includes 5 example tests demonstrating the pattern

Documentation:
- Add dual-mode testing section to CONTRIBUTING.md
- Document RunDualModeTest API and available helpers

Test Fixes:
- Fix sync_local_only_test.go gitPull/gitPush calls
- Add gate_no_daemon_test.go for beads-70c4 investigation

* fix(test): isolate TestFindBeadsDir tests with BEADS_DIR env var

The tests were finding the real project's .beads directory instead of
the temp directory because FindBeadsDir() walks up the directory tree.
Using BEADS_DIR env var provides proper test isolation.

* fix(test): stop daemon before running test suite guard

The test suite guard checks that tests don't modify the real repo's .beads
directory. However, a background daemon running auto-sync would touch
issues.jsonl during test execution, causing false positives.

Changes:
- Set BEADS_NO_DAEMON=1 to prevent daemon auto-start from tests
- Stop any running daemon for the repo before taking the "before" snapshot
- Uses exec to call `bd daemon --stop` to avoid import cycle issues

* chore: revert .beads/issues.jsonl to upstream/main

Per CONTRIBUTING.md, .beads/issues.jsonl should not be modified in PRs.
2026-01-06 12:52:19 -08:00
Steve Yegge
9544558840 ci: add check to reject PRs with .beads/issues.jsonl changes
Contributors frequently fork the repo and accidentally include their local
.beads/issues.jsonl changes in PRs. This adds:

1. A new CI job that fails PRs containing .beads/issues.jsonl changes
2. Clear error message with fix instructions
3. Updated CONTRIBUTING.md with guidance

This should prevent the common issue of PRs including unintended database changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-15 23:43:30 -08:00
Logan Thomas
520e1007f1
fix/doc: Go version inconsistencies and broken documentation links (#535)
* docs: fix Go version typo in CONTRIBUTING.md (1.25 -> 1.24)

* docs: update Go version requirement to 1.24+ across docs

* docs: fix broken links to docs/ in npm-package/README.md

* docs: fix QUICKSTART.md path reference in AGENTS.md
2025-12-13 10:48:44 -08:00
Steve Yegge
9c3ab7fba9 Document -short flag, update linting baseline, clarify bd edit MCP exclusion
- Enhanced CONTRIBUTING.md with -short flag usage guidance
- Updated LINTING.md: 22 issues baseline (down from 34)
- Added MCP exclusion note for bd edit command in AGENTS.md

Closes bd-iov0, bd-aec5439f, bd-fd8753d9
2025-11-06 19:42:01 -08:00
Steve Yegge
b31bddc210 Optimize test suite performance - 45% reduction in integration tests
- Add testutil.TempDirInMemory() using /dev/shm on Linux for 20-30% I/O speedup
- Update slow hash multiclone tests to use in-memory filesystem
- Convert 17 scripttest tests (~200+s) to fast CLI tests (31s) with --no-daemon
- Disable slow scripttest suite behind build tag
- Add README_TESTING.md documenting test strategy and optimizations
- Update CI to use -short flag for PR checks, full tests nightly

Results:
- TestHashIDs_* reduced from ~20s to ~11s (45% reduction)
- Scripttest suite eliminated from default runs (massive speedup)
- Total integration test time significantly reduced

Closes bd-gm7p, bd-l5gq

Amp-Thread-ID: https://ampcode.com/threads/T-c2b9434a-cd29-4725-b8e0-cbea50b36fe2
Co-authored-by: Amp <amp@ampcode.com>
2025-11-04 11:25:36 -08:00
Steve Yegge
9a109902b4 Consolidate documentation: move maintainer docs to docs/, remove redundant files
- Move RELEASING.md and LINTING.md to docs/ (maintainer-only content)
- Delete WORKFLOW.md (agent workflow content belongs in AGENTS.md)
- Delete TEXT_FORMATS.md (technical details belong in ADVANCED.md)
- Update all cross-references to point to new locations
- Keep CLAUDE.md (required by Claude Code)

Reduces root-level docs from 20 to 16 files with clearer organization.

Amp-Thread-ID: https://ampcode.com/threads/T-fe1db4f3-16c6-4a79-8887-c7f4c1f11c43
Co-authored-by: Amp <amp@ampcode.com>
2025-10-28 15:46:12 -07:00
Steve Yegge
2c7708eaa7 Address remaining golangci-lint findings
- Add package comment to cmd/bd/dep.go
- Change directory permissions from 0755 to 0750 in init.go
- Simplify getNextID signature (remove unused error return)
- Configure golangci-lint exclusions for false positives
- Document linting policy in LINTING.md

The remaining ~100 lint warnings are documented false positives:
- 73 errcheck: deferred cleanup (idiomatic Go)
- 17 revive: Cobra interface requirements and naming choices
- 7 gosec: false positives on validated SQL and user file paths
- 2 dupl: acceptable test code duplication
- 1 goconst: test constant repetition

See LINTING.md for full rationale. Contributors should focus on
avoiding NEW issues rather than the documented baseline.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-12 09:48:22 -07:00
Steve Yegge
87ed7c8793 Polish for open-source release
Major improvements to code quality, documentation, and CI:

Code Quality:
- Add golangci-lint configuration with 13 linters
- Fix unchecked error returns in export/import/init
- Refactor duplicate scanIssues code
- Add package comments for all packages
- Add const block comments for exported constants
- Configure errcheck to allow idiomatic defer patterns

Documentation:
- Add comprehensive CONTRIBUTING.md with setup, testing, and workflow
- Fix QUICKSTART.md binary name references (beads → bd)
- Correct default database path documentation

CI/CD:
- Add GitHub Actions workflow for tests and linting
- Enable race detection and coverage reporting
- Automated quality checks on all PRs

All tests passing. Lint issues reduced from 117 to 103 (remaining are
idiomatic patterns and test code). Ready for open-source release.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-12 09:41:29 -07:00