beads/AGENTS.md
gascity-eddie[bot] 4f9174e6ba
docs(agents): bazel test is authoritative; agents never run go test (#7695)
* docs(agents): bazel test is authoritative; agents never run go test

Agents run tests only with `bazel test`, also while iterating on one
behavior: AGENTS.md shows the focused form
(`bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$'`), the
target naming, that one --test_filter covers every target, that a cached
result for unchanged inputs is the same evidence, and that a new test file
needs `make bazel-sync` before Bazel runs it. `go test` (`./scripts/test.sh`,
`make test-go`) stays a convenience for humans working offline. TESTING.md's
focused red/green row and its plain-go-test section say the same.

Why: on the maintainer-city factory host, seats' own uncached `go test`
reruns of the same packages are the largest tool cost in adopt-pr, while
`bazel test` there executes on rbe-west and returns an unchanged target's
cached result in seconds.

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

* docs(agents): check that a focused test ran; exempt golden regeneration

Review fixes for #7695 (iterations 1 and 2).

The focused form exits 0 with "1 test passes" when the test never ran: a
filter that matches nothing, an integration-tagged file --config=ci does not
compile, the TestEmbedded* name skip, a -short skip, and a parent test whose
every subtest skipped (Go still prints "--- PASS" for the parent). It now
adds --test_output=all, and a run counts only when its log shows
"--- PASS: <TestName>" and no "--- SKIP" for the test or a <TestName>/...
subtest; a subtest that skips by design is left out with a subtest filter.

engdocs/TESTING.md gains "Check That the Test Ran"; AGENTS.md links there
instead of restating it. The section names the tests --config=ci does not
run and the way into each:
- Dolt-backed: the three --test_env flags, or the test's Dolt lane.
- -short-gated: --test_arg=-test.short=false.
- integration-tagged: --config=integration; the Dolt-backed ones of cmd/bd,
  tests/regression and internal/storage/dolt run in their Dolt-server lane
  target, whose env the suite needs. No lane runs those of other packages
  with Dolt, so a failure there is compared with the base commit first.
- TestEmbedded*: --test_arg=-test.skip= lifts the name skip; a test that
  then still skips for BEADS_TEST_EMBEDDED_DOLT=1 runs in its package's
  embedded-tagged target under --config=embedded (the cmd/bd and
  internal/storage/embeddeddolt targets are named).
- files BUILD.bazel does not list: make bazel-sync.
A lane's sh_test can hand the test binary its own -test.run, which
overrides --test_filter, so a trailing --test_arg=-test.run with sharding
disabled selects the test there. In a sharded target the other shards print
"testing: warning: no tests to run". The section also gives the
target-naming rule.

Golden regeneration (make corpus-regen, make githooks-regen,
BD_UPDATE_GOLDEN=1 ... go test, -update-ledger-doc) writes the source tree,
which a Bazel test cannot do: it runs from its runfiles tree, and on
rbe-west update mode fails with "permission denied". AGENTS.md and the new
"Regenerating Golden Files" section exempt these go test runs; where a host
refuses go test even for them, a maintainer regenerates. The factory seat
shim (gastownhall/workflows#102, scripts/seat-bin/go) still refuses update
mode and needs the same carve-out there.

Also: the plain-go-test opener scopes "humans working offline" to the
runner and its go test targets, so the Dolt-backend, fixture and
testing.Short() rules still bind agents; make ci-pr-core is marked plain go
test; the beads-docs skill's docsync gate is the Bazel target; RELEASING.md
and engdocs/RELEASE-STABILITY-GATE.md name the regression suite's Bazel
target (//tests/regression:regression_test under --config=doltserver-cmd)
in place of make test-regression, which is plain go test.

Measured on rbe-west (exit 0 unless noted). Iteration 1, at c4d5409895:
- a mistyped filter, and //internal/compact TestNew (integration-tagged)
  under --config=ci: "testing: warning: no tests to run"
- TestNew under --config=integration: "--- SKIP" (BEADS_TEST_SKIP=dolt);
  with the Dolt flags added it runs (and fails, exit 3, on the local
  backend: its store finds no "beads" database; outside this PR)
- TestConcurrentHeartbeatReclaimClose with the Dolt flags: "--- SKIP"
  (short mode); plus --test_arg=-test.short=false: "--- PASS"
- //cmd/bd:bd_embedded_test, sharding disabled: --test_filter alone ran
  TestEmbeddedUpdateConcurrent (manifest shard 1's test); the trailing
  -test.run ran "--- PASS: TestEmbeddedShowBasicsAndJSON"
- //scripts:go_test_sources_test
  TestEmbeddedCmdShardManifestBareWriteIsIdempotent: --config=ci "no tests
  to run"; plus --test_arg=-test.skip=: "--- PASS"
Iteration 2, at b1d25543aa (the same Go inputs):
- //internal/storage/dolt:dolt_test TestMoveIssuePersistenceInTxTransitions
  under --config=ci: "--- PASS" for the parent and "--- SKIP" for all 6
  subtests (BEADS_TEST_SKIP=dolt), "1 test passes"; with the Dolt flags and
  --test_filter='^TestMoveIssuePersistenceInTxTransitions$/^persistent-to-ephemeral$'
  "--- PASS" for the parent and that subtest only, no "--- SKIP"
- //internal/storage/embeddeddolt:embeddeddolt_test
  TestEmbeddedRemoteMigrateGate_BlocksReopen under --config=ci plus
  --test_arg=-test.skip=: "--- SKIP" (BEADS_TEST_EMBEDDED_DOLT unset);
  //internal/storage/embeddeddolt:embeddeddolt_embedded_test under
  --config=embedded, sharding disabled, trailing -test.run: "--- PASS"
  (the shard script listed 433 tests; only the named one ran)
- --config=ci plus --test_arg=-test.skip=: "--- PASS" for //tools/nogo
  TestEmbeddedConfigIsTheRepositoryConfig and //internal/tracker
  TestEmbeddedDoltExternalRefChangedAfterUsesHistoryFastPath
- sharding disabled, trailing -test.run: "--- PASS" for
  //internal/storage/dolt:dolt_server_full_test
  TestWispDeleteCascade_TransactionDeleteIssue under
  --config=doltserver-integration, and for //cmd/bd:bd_dolt_server_test
  TestCLI_ReopenClearsDeferUntil under --config=doltserver-cmd
- make check-docs: exit 0 (docsync: 10 test cases ran, none skipped)

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>

---------

Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-19 14:04:30 +00:00

12 KiB
Raw Permalink Blame History

Beads — Contributor Agent Instructions

This file is for agents and humans developing beads (bd). If you are using bd to track work in your own project, read the user docs instead: docs site and IDE and agent setup.

Nested AGENTS.md files hold area-specific rules; the routing table at the end lists them. CLAUDE.md files are symlinks to their sibling AGENTS.md.

How work flows here

GitHub Issues is the public tracker. Use an issue when it adds context reviewers need: a user-visible bug, a behavior or design change worth discussing, or work that spans several PRs. The issue carries the reproduction, impact, and evidence for a bug, or the motivation, impact, risk, and verification plan for a change. Small, self-explanatory changes (typos, flaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body explains the why.

  1. If the change warrants an issue, find or file one with the bug or feature form. It does not need maintainer approval first; file it before or alongside the PR.
  2. Work on a branch, open a PR against main (its body says Closes #<issue> when there is one), and let CI and review run.
  3. Maintainers triage issues with status/needs-triage, status/needs-info, status/needs-repro, status/needs-design, and status/accepted (confirmed); see CONTRIBUTING.md.

Maintainers also keep an internal bd ledger. It is optional for contributors and not a substitute for the GitHub issue.

Agent contribution policy

  • File an issue when the change warrants one (see above). When you do, use the bug or feature form fields, fill each from evidence, and answer NOT_ENOUGH_INFO where the evidence runs out.
  • A human reviews and stands behind every issue and PR an agent drafts. Evidence that the change works end-to-end is required; "unit tests pass" alone is not evidence.
  • Before implementing work, opening a PR, or merging/closing a PR, run the PR preflight:
    scripts/pr-preflight.sh --search "<topic keywords>" --repo gastownhall/beads
    scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads
    
    The preflight is the agent gate for PR handling; do not rely on auto-discovery of CONTRIBUTING.md.
  • Use gh for GitHub issues and PRs, not browser tools. Write PR, issue, comment, and review bodies to a file, run scripts/gh-body-lint <body-file>, and pass the file with gh ... --body-file. Sign agent-written GitHub comments and reviews per engdocs/AGENT_SIGNING.md.

Contributor protection

External contributor PRs have priority. Read CONTRIBUTING.md — it contains promises we've made to contributors — and, before triaging, reviewing, landing, closing, or otherwise maintaining PRs, PR_MAINTAINER_GUIDELINES.md. The maintainer policy is to maximize community throughput: find useful contributor value, absorb or transform it locally when practical, preserve attribution, and use request-changes only as a last resort.

Before implementing any feature or fix, check for existing open PRs on the same topic. If one exists:

  1. Review it first — read the diff, understand the approach.
  2. Build on their work, don't rewrite it — check out their branch, fix/adapt as needed.
  3. Preserve their tests — keep them unless they're wrong.
  4. Attribute properly — Co-authored-by: in commits, reference their PR.
  5. Never close or supersede their PR silently. If a rewrite is unavoidable, explain why on the original PR and credit their design/tests.

Scope: where a change belongs

Read engdocs/PROJECT_CHARTER.md before adding feature surface area. Beads owns issue tracking primitives and should not encode orchestration-layer policy, become a storage engine, or casually expand the database schema when metadata would work. Prefer, in order: issue metadata over new fields, a flag on an existing command over a new command, an integration or plugin over core, and leave orchestration policy to the orchestration layer.

Storage boundary. Beads talks to storage through a driver interface (dolthub/driver for Dolt). Do not add beads-side flocks, engine introspection, storage-specific retry or crash-recovery logic, or public SDK return types that leak driver internals. If the boundary is too narrow, widen the interface or route the issue to the driver instead of patching around it in beads. bd doctor support for embedded mode is enabled one subcommand at a time, each human-vetted (GH#3794): do not lift the embedded-mode gate in cmd/bd/doctor.go wholesale, and keep database-layer checks and fixes server-gated until the driver interface covers them.

Layering. Schema → internal/storage/issueops → cmd/bd. Add new primitives at the lowest layer first, one layer per PR, stacked when a fix spans layers. See CONTRIBUTING_PR_GUIDELINES.md.

Build, test, lint

Bazel is the build and test system: CI gates on the bazel test lanes in .github/workflows/bazel.yml, and nogo (lint + vet), gofmt and the repository guards exist only as Bazel targets. Install Bazelisk as bazel; the pre-commit and pre-push hooks need it.

make test          # bazel test //... --config=ci: the CI test lane (nogo, gofmt, guards, unit tests)
make check         # testing.Short policy + make ci-pr-lint + make test
make ci-pr-lint    # nogo lint + vet gate, native plus windows/darwin
make check-docs    # bazel docsync + doc freshness, then the CLI flag check
make bazel-sync    # after adding/removing/renaming Go files or changing imports/go.mod
make install       # build and install bd to ~/.local/bin (canonical)
  • Each other tier has its own lane (--config=integration, doltserver, embedded, ...); engdocs/TESTING.md lists the exact command per lane and is the canonical source for test selection, design, and PR-readiness gates.

  • Where actions run: contributors add --config=fork-cache (rbe-west's anonymous read-only cache; nothing is uploaded), maintainers with an rbe-west certificate --config=remote-exec, agent hosts whose ~/.bazelrc names the executor neither. Make yours the default with a build --config=... line in the gitignored .bazelrc.local, or pass BAZEL_FLAGS=... to make.

  • Agents run tests only with bazel test, also while iterating on one behavior:

    bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$' --test_output=all
    

    A target also passes when the test never ran (a filter that matches nothing, a skip, a file the configuration does not compile), so count a run only when its log shows --- PASS: TestName and no --- SKIP for the test or a TestName/... subtest: Go prints --- PASS for a test whose every subtest skipped. "Check That the Test Ran" in engdocs/TESTING.md names the tests --config=ci does not run (Dolt-backed, -short-gated, integration-tagged, TestEmbedded* and embedded-Dolt, files BUILD.bazel does not list) and the way into each. An unchanged target returns its cached result, which is the same evidence. Finish with make test.

  • Agents do not run go test (./scripts/test.sh, make test-go): CI does not enforce it, it skips nogo, gofmt and the guards, and agent hosts may refuse it. It stays a convenience for humans working offline. The exception is regenerating golden files (make corpus-regen, make githooks-regen, BD_UPDATE_GOLDEN=1), which Bazel cannot do: see "Regenerating Golden Files" in engdocs/TESTING.md.

  • Do NOT use go build -o bd ./cmd/bd, go install ./cmd/bd, or raw go run ./cmd/bd ...: they bypass the canonical build path, leave stale binaries, and raw go run misses the gms_pure_go tag. Use make install, ./bd, or go run -tags gms_pure_go ./cmd/bd ....

  • All new features need tests.

  • Never pollute a production database with test issues. Use t.TempDir() in Go tests and a disposable working directory for manual bd experiments.

  • make ci-pr-lint must pass with zero issues; see engdocs/LINTING.md.

  • If BUILD files are out of sync and you cannot run make bazel-sync, CI syncs them: on same-repo PRs the bazel-autofix workflow pushes the fix to your branch (pull before pushing again); fork PRs get a comment with an apply recipe.

  • If you changed behavior, update the user docs (docs/, via the beads-docs skill) or README in the same PR.

Commits and PRs

  • Conventional Commits: type(scope): summary (fix, feat, docs, test, refactor, chore, ci, perf).
  • For agent-prepared commits, include the Agent-Signature: trailer described in engdocs/AGENT_SIGNING.md. Use unknown-model or unknown-reasoning when reliable runtime metadata is unavailable.
  • Maintainers working from the internal ledger may also end the subject with the bead ID, e.g. (bd-abc), so bd doctor can detect orphaned issues.
  • Work on a feature branch and open a PR against main; direct pushes to main are reserved for releases and narrow operational fixes.
  • When the user asks to bump the version, use ./scripts/bump-version.sh; the full release process is in RELEASING.md.

Ending a session

Do not push to main. Before handing off:

  1. Run the quality gates your change needs (make test, make ci-pr-lint, and the other Bazel lanes engdocs/TESTING.md selects). If gates are broken on main, report it as a P0 issue.
  2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).
  3. Commit, push, or open a PR only when the person you are working for asked you to. Report changed files, validation run, and anything left open.

CLI output

NEVER use emoji-style icons (🔴🟠🟡🔵⚪) in CLI output. ALWAYS use small Unicode symbols with semantic colors: status ○ ◐ ● ✓ ❄; priority as a P0–P4 label with color (no status glyph). The full visual design system and CLI design principles are in engdocs/UI_PHILOSOPHY.md.

Non-interactive shell commands

Agents cannot answer prompts. Use cp -f, mv -f, rm -f, rm -rf, cp -rf (these may be aliased to -i); scp/ssh -o BatchMode=yes; apt-get -y; HOMEBREW_NO_AUTO_UPDATE=1 brew. DO NOT use bd edit — it opens $EDITOR; use bd update <id> --title/--description/--design/--acceptance/--append-notes (pipe text with special characters via --description=-).

Routing table

When you are touching… Read first
cmd/bd/ (commands, output, proxied-server routes) cmd/bd/AGENTS.md
engdocs/ (contributor and internals docs) engdocs/AGENTS.md
docs/ (the published user docs) .claude/skills/beads-docs/SKILL.md
Any Go test engdocs/TESTING.md
Lint failures or .golangci.yml engdocs/LINTING.md
A new storage operation or issueops role engdocs/ADDING_AN_ISSUEOPS_ROLE.md
Schema migrations internal/storage/schema/migrations/README.md
Dolt concurrency, server vs embedded mode engdocs/design/dolt-concurrency.md
Errors returned to users engdocs/ERROR_HANDLING.md
The bd serve HTTP surface engdocs/SERVE_RUNBOOK.md
A new example under examples/ examples/README.md — give the example its own README and link it there
Releases and version bumps RELEASING.md
Scope questions engdocs/PROJECT_CHARTER.md
Planned work and priorities ROADMAP.md