[anakanemison]

Part 12 of 23 of a stacked series (tracking issue: #35). Based on U11-linker-param-file-refusal, the previous part: review and merge that first.

Kind: guidance. Lab proposal: P10, P13.

What the migration runs showed

Agents changed the reference configuration mid-run to make a diff converge, and put settings in bazel_args or a named config, so plain bazel build //... was never compared. In the lab's later runs, every migrating run recorded its configure command and kept settings in .bazelrc.

The change (2 commits)

Require parity for the default bazel invocation

bazel_args records the extra args aquery runs with to mirror the real
build. Nothing said where settings the migration itself introduces should
live, so parity could be established for a named --config that a plain
bazel build //... never applies: the claim then holds for a command no
user runs.

Measured in any2bazel-lab: one pono migration put the
reference's Release settings behind --config=release, recorded it in
bazel_args, and converged. A plain bazel build //... produced an
assertion-enabled binary that crashes on an input where the reference
prints an error and exits. The four other runs on the same project put the
settings in .bazelrc's build lines and were equivalent.

Adds one bullet to the "invoke aquery the way the project is built"
list: settings the migration adds go in .bazelrc build lines, and parity
must hold for the project's documented build command, which is a plain
bazel build //... unless the project documents flags; only those
documented flags go in bazel_args. The bazel_args field
description now says the same, and that the example config (a project
config plus the top-level -fno-exceptions BoringSSL expects) is that kind of
entry.

In the lab's later pono and lensfun runs with this change, bazel_args was
empty and the settings were in .bazelrc build lines.

Pin the reference configuration and record its command

Nothing in the procedure said which CMake configuration the reference
should use, or that choosing one is a decision. An agent can turn options
off before extracting the reference and then reach parity with that
narrower build; both sides of the comparison move together, so no error
count shows it.

Measured in any2bazel-lab: a MySQL Server migration
configured the reference with Router, NDB, the unit tests and the
distribution's package compiler flags all turned off, recorded only in a
comment in any2bazel.json. Against the project's default configuration the
result showed 4,928 differences; against its own, 13. The reason given for
the package flags was defensible; the problem was that the choice was
silent. Agents redefined the reference with and without the skill, on small
projects as well as large.

"Extract the reference model" now says to configure with the project's
documented default options, to surface any change as a scope decision, and
to record
the exact command in any2bazel.json as reference.configure_command (added
to the example and the field list as record-only; config.load ignores it,
like any unknown key) and never change it after the first diff. The
optional test step reconfigures with tests on; that command is recorded
separately, as reference.test_configure_command, so it does not count as
changing the reference.

In the lab's later runs with this change, every migrating agent recorded
its configure command.

Testing

pytest tests/ at this commit: 196 passed (130 on main).

🤖 Generated with Claude Code