beads/engdocs
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
..
adr fix(init): refuse to initialize directly in the home directory (#4635) (follow-up to #4795) (#7609) 2026-10-16 13:52:00 +00:00
decisions docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) 2026-07-17 18:03:28 -07:00
design feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649) 2026-10-17 12:29:13 +00:00
staged-for-removal docs: pin the Dolt version instead of steering users to releases/latest (ga-m0dlk) (#5899) 2026-08-20 22:41:24 -07:00
ADDING_AN_ISSUEOPS_ROLE.md feat(journalops): the mutation journal becomes the third facade namespace (#5552) 2026-08-10 10:58:05 -07:00
AGENT_SIGNING.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
AGENTS.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
ATTRIBUTION.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
BDP_BEAD_GRAPH_PLAN.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
BDP_GRAPH_ARCHITECTURE.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
BDP_GRAPH_CLI_AND_STORAGE_SPEC.md BDP bead-graph plan and W-arch design docs (P-1 rulings complete; docs-only) (#6154) 2026-09-28 22:12:19 -07:00
CI_CLEANUP_PLAN.md fix(preflight): share checkout lint authority (#5780) 2026-09-30 22:41:55 -07:00
CI_REQUIRED_CHECK_TOPOLOGY.md ci(bazel): dolt-int gates server-storage + cmd-dolt in mode remote (item 5 A2) (#7535) 2026-10-13 09:17:54 +00:00
CI_TEST_SURFACE_AUDIT.md ci(bazel): pin the slowest cmd/bd Dolt-server tests to their own shards (#7413) 2026-10-09 05:50:09 +00:00
CLAUDE.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
COLLISION_MATH.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
complexity-baseline.txt ci: add advisory cyclomatic complexity reporting (#6081) 2026-08-30 19:05:17 -07:00
COMPLEXITY_TRACKING.md ci: add advisory cyclomatic complexity reporting (#6081) 2026-08-30 19:05:17 -07:00
CONTRIBUTOR_NAMESPACE_ISOLATION.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
DOC_INVENTORY.md ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341) 2026-10-07 05:17:22 +00:00
ERROR_HANDLING.md docs(engdocs): re-review ERROR_HANDLING.md against cmd/bd and refresh its marker (#7267) 2026-10-06 12:46:26 -07:00
EXCLUSIVE_LOCK.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
EXTENDING.md perf(storage): SearchIssueSummaries narrow-projection foundation (be-nu4.3) (#3458) 2026-10-01 01:19:24 -07:00
ICU-POLICY.md ci(bazel): run the upgrade smoke tests under Bazel; retire cross-version-smoke.yml (#7331) 2026-10-07 02:49:39 +00:00
INTEGRATION_CHARTER.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
INTERNALS.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
LINTING.md ci: F5 S2 Variant A — nogo ownership for the integration configuration group (#7486) 2026-10-10 23:19:16 +00:00
messaging.md fix(doctor): recommend 'bd prune' instead of nonexistent 'bd cleanup' (#5829) 2026-08-20 05:30:47 -07:00
PERFORMANCE_TESTING.md docs(engdocs): point storage test and bench references at the Dolt packages 2026-07-18 02:43:57 +00:00
PROJECT_CHARTER.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
README_TESTING.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
RELEASE-STABILITY-GATE.md docs(agents): bazel test is authoritative; agents never run go test (#7695) 2026-10-19 14:04:30 +00:00
RELEASING.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
REPO_CONTEXT.md fix(context): resolve from .beads when outside a git repository (#4772) (#4792) 2026-10-01 07:08:12 -07:00
RULES_AUDIT_DESIGN.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
SECURITY-DEPENDENCY-EXCEPTIONS.md Bump Go to 1.26.5 (#4942) 2026-07-23 18:54:32 -07:00
SERVE_RUNBOOK.md feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649) 2026-10-17 12:29:13 +00:00
TESTING.md docs(agents): bazel test is authoritative; agents never run go test (#7695) 2026-10-19 14:04:30 +00:00
TESTING_PHILOSOPHY.md docs(test): make TESTING.md canonical (bd-mrs20) (#5226) 2026-08-01 02:30:21 -07:00
UI_PHILOSOPHY.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00