product-vamp/docs/composer/commands.md

# Reproduction commands and release gate

Prefix from the repository root:

```sh
build/build_common/python/bin/python3 build/build_tools/python_runner.py build/build_common/modulus
```

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/structured/dependency
```

Development-only stateful derivation / complete-output fitting (use `explain` instead of `fit` for coverage alone). Install the optional solver with repository Python and `-m pip install --target build/development_packages -r audition/requirements-training.txt`. Production does not load that directory:

```sh
-m audition.fit_selection fit --passes 8 --solver-path build/development_packages \
 --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/structured/cache --output build/solo_reference_comparison/structured/fitting
```

Production stage (no reference arguments):

```sh
-m generator --data-dir data --output-dir build/solo_reference_comparison/structured/staged \
 --static-assets-dir package/assets --check --jobs 2 --composition-jobs 2 \
 --composition-cache build/solo_reference_comparison/structured/verified-cache \
 --engraving-cache build/build_common/engraving_cache --export-solo-xml --trace-level full \
 --profile-output build/solo_reference_comparison/structured/build-profile.json --progress
```

Exact gate after generation:

```sh
-m audition.solo_compare --generated-dir build/solo_reference_comparison/structured/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 \
 --baseline-dir build/solo_reference_comparison/structured/baseline/solo_xml \
 --assets build/solo_reference_comparison/structured/staged \
 --output build/solo_reference_comparison/structured/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.

Source-only four-bar completed alternatives (the XML marked candidate 1 is the automatic winner):

```sh
-m audition.phrase_candidates --source data/songs/all-of-me.xml --role acoustic_solo \
 --bars 4 --cache-dir build/solo_reference_comparison/structured/cache \
 --output build/solo_reference_comparison/structured/four-bar
```

No solver output or constrained derivation may replace an ordinary production score.
The exact four-complete-output gate remains mandatory. Reference absence proves a
runtime boundary only; learned coefficients still depend on their training data.

A completed ordinary build can supply the negative candidates for one learning
round without repeating inference just to reconstruct its report. Use
`-m audition.train_completed` with the same `--source`, `--reference`, `--role`,
and `--form-start` case arguments, plus `--completed-dir <assets>`,
`--solver-path build/development_packages`, and `--output <development-round>`.
`--stage-data` creates a separate production-data copy with the proposed shared
weights. It does not edit `data/` or published assets. Feed that copy to the normal
`-m generator --data-dir ...` command for a new cold target-free build, then run
the complete four-output exact gate. A solver that separates eight saved
candidates has not demonstrated exact generation.

For later complete-output rounds, add `--previous-round <earlier-training.json>`
to retain prior counterexamples. Incompatible source/example identities,
evaluation versions or fixed musical policy are rejected. Only learned weights
may change between compatible rounds. Do not fit only the latest eight outputs
and silently forget the earlier failures.

The first proposed model's ordinary trial uses the same production command with
`--data-dir .../round-1/data --output-dir .../learned-stage`, separate
`--composition-cache .../learned-cache`, `--composition-jobs 4`, and
`--profile-output .../learned-build-profile.json`. This process receives no
reference arguments. Comparison and learning are separate later commands.

The completed second fit used `--data-dir .../round-1/data`,
`--completed-dir .../learned-stage`,
`--previous-round .../round-1/evidence/training.json`, and
`--output .../round-2`, with the same four source/reference/role arguments.
It accumulated 64 full-output inequalities. Its successful solver status is
not a release: the acoustic openings still fail the strict cutoff diagnosis,
and no third complete ordinary rollout was performed.

Final focused tests were run with `PYTHONPATH=build/development_packages` and
`-m unittest tests.test_joint_actions tests.test_structured_selection` (35 passed).
The latest dependency check uses `--output .../dependency-cached`.
The read-only staged verification script also accepts
`--stage learned-stage --data-dir .../round-1/data --prefix learned-`.
All comparison artifacts are linked from `structured/index.html`.