Cleanup

docs/composer/commands.md

@@ -1,35 +1,53 @@
-# Reproduction commands
+# Reproduction commands and release gate
 
-Use this prefix from the repository root:
+Prefix from the repository root:
 
 ```sh
 build/build_common/python/bin/python3 build/build_tools/python_runner.py build/build_common/modulus
 ```
 
-Staged generation:
-
-```sh
--m generator --data-dir data --output-dir build/solo_reference_comparison/.staging --static-assets-dir package/assets --check --jobs 2 --composition-jobs 2 --composition-cache build/build_common/composition_cache --engraving-cache build/build_common/engraving_cache --export-solo-xml --trace-level full --profile-output build/solo_reference_comparison/build-profile.json --progress
-```
-
-Publish normally with `cmake --build build/build_x86_debug --target vamp_generated_assets -j2`. Preserve the previous completed exports under `build/solo_reference_comparison/previous/solo_xml/` before replacing assets. Copy the checked stage's `solo_xml/` into `build/solo_reference_comparison/generated/` to retain full decision reports, and verify its musical/XML equality with normal publication.
-
-```sh
--m audition.solo_compare --generated-dir build/solo_reference_comparison/generated --baseline-dir build/solo_reference_comparison/previous/solo_xml --reference all_of_me/acoustic=build/all-of-me-solo-1.xml --reference all_of_me/electric=build/all-of-me-solo-2.xml --reference autumn_leaves/acoustic=build/autumn-leaves-solo-1.xml --reference autumn_leaves/electric=build/autumn-leaves-solo-2.xml --form-start autumn_leaves/acoustic=2 --form-start autumn_leaves/electric=2 --form-start all_of_me/acoustic=1 --form-start all_of_me/electric=1 --reference-pitch guitar-written --assets build/build_x86_debug/generated_assets --output build/solo_reference_comparison
-```
-
-Full relationship/rule review:
-
-```sh
--m audition.theory_review --reference all_of_me/acoustic=build/all-of-me-solo-1.xml --reference all_of_me/electric=build/all-of-me-solo-2.xml --reference autumn_leaves/acoustic=build/autumn-leaves-solo-1.xml --reference autumn_leaves/electric=build/autumn-leaves-solo-2.xml --source all_of_me=data/songs/all-of-me.xml --source autumn_leaves=data/songs/autumn_leaves.xml --generated-dir build/solo_reference_comparison/generated --output build/solo_reference_comparison/analysis
-```
-
-Tests:
+The commands below go after that prefix. They write only the consolidated repair directory. Existing published assets and the baseline remain separate.
 
 ```sh
 -m unittest discover -s tests -p 'test_*.py'
--m audition.dependency_check --output build/solo_reference_comparison/dependency
--m audition.transfer_review --output build/solo_reference_comparison/transfer
+-m audition.dependency_check --output build/solo_reference_comparison/repair/dependency
 ```
 
-Individual-role generation remains `-m generator.compose --song ... --role acoustic_solo --data-dir data --cache-dir ... --output ... --solo-xml ...`. No other part is generated as a musical input. The one comparison folder is downstream and disposable.
+Development-only derivation/fitting (use `explain` instead of `fit` for coverage alone):
+
+```sh
+-m audition.fit_selection fit --passes 200 \
+ --source all_me_a=data/songs/all-of-me.xml --source all_me_e=data/songs/all-of-me.xml \
+ --source autumn_a=data/songs/autumn_leaves.xml --source autumn_e=data/songs/autumn_leaves.xml \
+ --reference all_me_a=build/all-of-me-solo-1.xml --reference all_me_e=build/all-of-me-solo-2.xml \
+ --reference autumn_a=build/autumn-leaves-solo-1.xml --reference autumn_e=build/autumn-leaves-solo-2.xml \
+ --role all_me_a=acoustic_solo --role all_me_e=electric_solo \
+ --role autumn_a=acoustic_solo --role autumn_e=electric_solo \
+ --form-start all_me_a=1 --form-start all_me_e=1 --form-start autumn_a=2 --form-start autumn_e=2 \
+ --cache-dir build/solo_reference_comparison/repair/cache --output build/solo_reference_comparison/repair/fitting
+```
+
+Production stage (no reference arguments):
+
+```sh
+-m generator --data-dir data --output-dir build/solo_reference_comparison/repair/staged \
+ --static-assets-dir package/assets --check --jobs 2 --composition-jobs 2 \
+ --composition-cache build/solo_reference_comparison/repair/cache \
+ --engraving-cache build/build_common/engraving_cache --export-solo-xml --trace-level full \
+ --profile-output build/solo_reference_comparison/repair/build-profile.json --progress
+```
+
+Exact gate after generation:
+
+```sh
+-m audition.solo_compare --generated-dir build/solo_reference_comparison/repair/staged/solo_xml \
+ --reference all_of_me/acoustic=build/all-of-me-solo-1.xml --reference all_of_me/electric=build/all-of-me-solo-2.xml \
+ --reference autumn_leaves/acoustic=build/autumn-leaves-solo-1.xml --reference autumn_leaves/electric=build/autumn-leaves-solo-2.xml \
+ --form-start all_of_me/acoustic=1 --form-start all_of_me/electric=1 \
+ --form-start autumn_leaves/acoustic=2 --form-start autumn_leaves/electric=2 \
+ --reference-pitch guitar-written --output build/solo_reference_comparison/repair/comparison --require-exact
+```
+
+`--require-exact` returns 1 on any sounding-event/rest mismatch; it does not reinterpret a similar style as success. Add `--assets <completed-assets>` for consistent neutral rendering. A failed fit or exact gate is not permission to copy targets, promote a target-constrained derivation, or publish a mismatched stage. Normal CMake publication is intentionally deferred until the approved acceptance gate passes.
+
+Individual roles remain available through `-m generator.compose --song ... --role acoustic_solo --data-dir data --cache-dir ... --output ... --solo-xml ...`. Use `-m audition.benchmark --source ... --role ... --cache ... --output ...` for an isolated measurement after other builds/tests/fits stop. Profiling changes measured runtime; do not compare a cProfile run to an unprofiled build as a speedup ratio.