Cleanup

docs/composer/commands.md

@@ -10,13 +10,13 @@ The commands below go after that prefix. They write only the consolidated repair
 
 ```sh
 -m unittest discover -s tests -p 'test_*.py'
--m audition.dependency_check --output build/solo_reference_comparison/repair/dependency
+-m audition.dependency_check --output build/solo_reference_comparison/structured/dependency
 ```
 
-Development-only derivation/fitting (use `explain` instead of `fit` for coverage alone):
+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 200 \
+-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 \
@@ -24,30 +24,83 @@ Development-only derivation/fitting (use `explain` instead of `fit` for coverage
  --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
+ --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/repair/staged \
+-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/repair/cache \
+ --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/repair/build-profile.json --progress
+ --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/repair/staged/solo_xml \
+-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 --output build/solo_reference_comparison/repair/comparison --require-exact
+ --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`.