* 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>
227 lines
12 KiB
Markdown
227 lines
12 KiB
Markdown
# 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](https://beads.gascity.com/) and
|
||
[IDE and agent setup](docs/getting-started/ide-setup.md).
|
||
|
||
<!-- Contributor-only file. Do not run `bd setup` or `bd init` against this
|
||
checkout: they would inject the end-user beads integration block here. -->
|
||
|
||
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](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:
|
||
```bash
|
||
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](engdocs/AGENT_SIGNING.md).
|
||
|
||
## Contributor protection
|
||
|
||
External contributor PRs have priority. Read [CONTRIBUTING.md](CONTRIBUTING.md)
|
||
— it contains promises we've made to contributors — and, before triaging,
|
||
reviewing, landing, closing, or otherwise maintaining PRs,
|
||
[PR_MAINTAINER_GUIDELINES.md](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](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](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](https://github.com/bazelbuild/bazelisk) as `bazel`; the pre-commit
|
||
and pre-push hooks need it.
|
||
|
||
```bash
|
||
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](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:
|
||
|
||
```bash
|
||
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](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](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](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](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](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](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](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](cmd/bd/AGENTS.md) |
|
||
| `engdocs/` (contributor and internals docs) | [engdocs/AGENTS.md](engdocs/AGENTS.md) |
|
||
| `docs/` (the published user docs) | `.claude/skills/beads-docs/SKILL.md` |
|
||
| Any Go test | [engdocs/TESTING.md](engdocs/TESTING.md) |
|
||
| Lint failures or `.golangci.yml` | [engdocs/LINTING.md](engdocs/LINTING.md) |
|
||
| A new storage operation or issueops role | [engdocs/ADDING_AN_ISSUEOPS_ROLE.md](engdocs/ADDING_AN_ISSUEOPS_ROLE.md) |
|
||
| Schema migrations | [internal/storage/schema/migrations/README.md](internal/storage/schema/migrations/README.md) |
|
||
| Dolt concurrency, server vs embedded mode | [engdocs/design/dolt-concurrency.md](engdocs/design/dolt-concurrency.md) |
|
||
| Errors returned to users | [engdocs/ERROR_HANDLING.md](engdocs/ERROR_HANDLING.md) |
|
||
| The `bd serve` HTTP surface | [engdocs/SERVE_RUNBOOK.md](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](RELEASING.md) |
|
||
| Scope questions | [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) |
|
||
| Planned work and priorities | [ROADMAP.md](ROADMAP.md) |
|