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

227 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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) |