build: clarify makefile target names and restructure ci

.claude/skills/mx-api-add-feature/SKILL.md

@@ -63,9 +63,9 @@ write paths symmetric. See ./steps/step-3-mx-impl.md
 
 ## Step 4: Run tests
 
-Run `make test` for the unit suites and `make test-api-roundtrip` for the corpus roundtrip gate
-(Step 1 explains both, along with `make discover-api-roundtrip`). Verify everything passes. Then run
-`make fmt` and `make check` so the CI quality gates will pass.
+Run `make api-test` for the unit suites and `make api-roundtrip` for the corpus roundtrip gate
+(Step 1 explains both, along with `make api-roundtrip-discover`). Verify everything passes. Then run
+`make fmt` and `make fmt-check` so the CI quality gates will pass.
 
 ## (optional) Step 5: Open a PR
 

.claude/skills/mx-api-add-feature/steps/step-1-test-strategy.md

@@ -16,7 +16,7 @@ There are two kinds of api tests.
 
 - Location: `src/private/mxtest/api/` (e.g. `NoteDataTest.cpp`, `DirectionDataTest.cpp`,
   `MeasureDataTest.cpp`, `PitchDataTest.cpp`, `MetronomeApiTest.cpp`).
-- They compile into the `mxtest` binary and run via `make test`.
+- They compile into the `mxtest` binary and run via `make api-test`.
 - Every file is gated by `#include "mxtest/control/CompileControl.h"` then
   `#ifdef MX_COMPILE_API_TESTS ... #endif`. That flag is defined in
   `src/private/mxtest/control/CompileControl.h` (currently always on). Wrap any new test file the
@@ -65,13 +65,13 @@ side, and run a strict DOM compare (`mxtest/corert/Compare`). Zero tolerance on
 
 - `regression <dataRoot> <baselineFile>`: runs only the files listed in
   `src/private/mxtest/api/roundtrip-baseline.txt`. Non-zero exit on any failure. This is the CI
-  gate. Run with `make test-api-roundtrip`. CI runs it in `.github/workflows/ci.yaml` (the
-  `linux-api` job step "Run corpus api roundtrip (regression mode)" and again in the docker job).
+  gate. Run with `make api-roundtrip`. CI runs it in `.github/workflows/ci.yaml` (the `test-linux`
+  job via `make test-all`, and again natively on macOS/Windows).
 - `discovery <dataRoot>`: walks the whole corpus (excludes `expected/`, `testOutput/`,
   `generalxml/`, `smufl/`, `*.fixup.xml`, `*.features.xml`, `corpus.xml`, `api.features.xml`, and
   any file with a sibling `*.invalid` marker), prints one tab-separated line per file
   `PASS|FAIL|SKIP|LOADFAIL|GETDATAFAIL|CREATEFAIL <tab> relpath <tab> detail`, and always exits 0.
-  Run with `make discover-api-roundtrip`. Never a gate.
+  Run with `make api-roundtrip-discover`. Never a gate.
 
 `roundtrip-baseline.txt` is a growing pinned list (~140 files across
 ksuite/lysuite/musuite/mjbsuite/custom/synthetic; see the file's header). It grows only by
@@ -90,8 +90,8 @@ genuinely survives the strict compare.
 
 ## Build note
 
-`make test-api-roundtrip` and `make discover-api-roundtrip` depend on the `dev` target (builds
-`mxtest-api-roundtrip`); `make test` builds and runs `mxtest` (the unit tests) plus examples.
+`make api-roundtrip` and `make api-roundtrip-discover` depend on the `api-build` target (builds
+`mxtest-api-roundtrip`); `make api-test` builds and runs `mxtest` (the unit tests) plus examples.
 
 ## Procedure
 
@@ -103,7 +103,7 @@ Do these in order. The discovery snapshot must be captured before you implement.
    MusicXML shape and attribute set.
 
 2. Capture the pre-implementation discovery baseline:
-   `make discover-api-roundtrip > /tmp/api-discovery-before.txt`. This is your reference for which
+   `make api-roundtrip-discover > /tmp/api-discovery-before.txt`. This is your reference for which
    corpus files fail and WHY (the `detail` column). Keep it.
 
 3. Grep that snapshot for files whose failure looks attributable to the missing feature -- e.g.
@@ -135,7 +135,7 @@ Do these in order. The discovery snapshot must be captured before you implement.
 8. Make the unit test pass (green); iterate until your new `TEST(...)` cases pass (SKILL.md Step 4
    owns the test/fmt/check commands).
 
-9. Re-run discovery and diff: `make discover-api-roundtrip > /tmp/api-discovery-after.txt`, then
+9. Re-run discovery and diff: `make api-roundtrip-discover > /tmp/api-discovery-after.txt`, then
    `diff /tmp/api-discovery-before.txt /tmp/api-discovery-after.txt`. Look for files that moved to
    `PASS` (or whose `FAIL` detail changed). For each newly-PASSing file, confirm the pass is
    actually attributable to your feature (re-read the file; check the old `detail` named your

.claude/skills/mx-api-classify-roundtrip-failures/SKILL.md

@@ -52,13 +52,13 @@ to be absorbed in test normalization later (#214).
 If `build/api/roundtrip-dump/` is empty or stale (api/impl changed since it was written), run:
 
 ```
-make dump-api-roundtrip
+make api-roundtrip-dump
 ```
 
 Then always run:
 
 ```
-make classify-api-roundtrip
+make api-roundtrip-classify
 ```
 
 Read the stdout summary it prints -- status counts, the distance histogram, the ranked worklist,

.github/instructions/corpus-and-tests.instructions.md

@@ -8,12 +8,12 @@ applyTo: "data/**,src/private/mxtest/**"
 - Adding or removing a corpus file requires: the pinned count bump in
   `src/private/mxtest/corert/CoreRoundtripTest.cpp`, regenerated audit artifacts
   (`make audit`: the `*.features.xml` sidecar and `data/corpus.xml`), and a green
-  `make test-core-dev`. Flag a corpus change missing any of these.
+  `make core-roundtrip-test`. Flag a corpus change missing any of these.
 - A deliberately unparseable file needs a sibling `<name>.invalid` marker explaining why; a
   schema-invalid-but-lenient file needs a `<name>.fixup.xml` sidecar. New fixups must follow
   the uniform leniency policy in `data/README.md`, not invent per-file rules.
 - `roundtrip-baseline.txt` (the api round-trip pass list) only grows by deliberate commits;
   flag removals or unexplained churn.
 - `ApiLoadSmokeTest` only proves a file imports without crashing; a feature claim needs a
-  fixture pinned in the read->write->read gate (`make test-api-roundtrip`).
+  fixture pinned in the read->write->read gate (`make api-roundtrip`).
 - Test code follows the same C++ rules as the library (no new anonymous namespaces).

.github/instructions/cpp.instructions.md

@@ -8,7 +8,7 @@ Repo-wide C++ rules (see AGENTS.md):
   get named functions (`tokenIsNameChar`); file-local constants get a per-type prefix
   (`kYesNoWire`). Existing anonymous namespaces are being retired as touched; do not demand
   drive-by fixes.
-- Formatting is enforced by clang-format (`make fmt` / `make check`); do not comment on layout
+- Formatting is enforced by clang-format (`make fmt` / `make fmt-check`); do not comment on layout
   the formatter controls.
 - Keep source ASCII.
 - Comments should state constraints and effects hard to ascertain from the code.

.github/instructions/gen.instructions.md

@@ -17,6 +17,6 @@ C++ (`gen/cpp`, the product), Go, C, JSON Schema. Review against its cardinal ru
 - Fail loud: new error paths must exit non-zero with a `template:line` style message, never
   emit best-effort output.
 - Generated output is committed: a generator change without its regenerated output (or vice
-  versa) fails `make test-gen` drift checking.
+  versa) fails the CI drift check (`make gen` then `git diff --exit-code`).
 - Template identifiers must be unity-build safe: use `{{ident}}`-suffixed names for
   file-local symbols.

.github/instructions/generated-core.instructions.md

@@ -7,6 +7,6 @@ Everything in this directory is GENERATED by `gen/` (`make gen-cpp`) from the Mu
 - Do not review style, naming, or repetition here; the generator owns those.
 - A diff in these files must be accompanied by a change under `gen/` (templates, config, or
   generator code) that produces it. Flag any hand edit -- it will be destroyed on the next
-  regeneration, and CI (`make test-gen`) fails on regeneration drift.
+  regeneration, and the CI drift check (`make gen` then `git diff --exit-code`) fails on it.
 - Review the paired `gen/` change instead, and check the generated diff only for evidence of an
   unintended blast radius (e.g. an edit meant for one type changing hundreds of files).