docs(cli,ledger): sweep #159 demo-retirement drift — stale comments + ledger notes

Cycle-close audit tidy for the #159 demo-retirement arc: behaviour-free reword of prose/comments/docs left pointing at symbols the arc deleted. Adversarially verified by the audit workflow; cargo build --workspace --all-targets green. - README: drop the removed `--harness` token; restrict the legacy built-in form claim to walkforward/mc/generalize (run/sweep no longer resolve one). - glossary: the built-in `--strategy` sweep surface is retired (#159), not a live inline path. - INDEX.md ledger: append [HISTORY] supersession markers (house style) to the dated realization notes advertising the retired `--harness` / built-in `--strategy` CLI forms (cost-flag #153, cycles 0065/0066/0067, name-res, #210 status); historical text preserved. - aura-engine test-fixture docs: drop dead cross-crate refs to the deleted aura-cli fns sample_harness / build_sample and the deleted `macd` composite. - cli_run.rs: reword the #159-cut-2 pin doc to the current clap generic-usage reality (no strategy_from / Strategy::RBreakout); r_sma_sweep_family -> blueprint_sweep_family. - verb_sugar.rs: fix the pre-existing `E[R]` unresolved-doc-link warning. Remaining tidy — the main.rs comment cluster plus its rustdoc link at :1546 (the second cargo-doc warning) — held for a follow-up issue. The dead cost-graph branch is tracked in #221. refs #159
2026-07-08 11:12:22 +02:00
parent ee7001647c
commit 07a73fb66e
7 changed files with 39 additions and 22 deletions
@@ -44,9 +44,9 @@ Invoke it as `aura <command> …` (examples below use the plain name).
 ## Running & orchestrating a loaded blueprint

 These verbs all take the **blueprint file as their first positional argument**
-and drive a family of runs over it. (Each verb also has a legacy built-in form
-selected by `--strategy`/`--harness` instead of a `.json` path, for the
-engine's own bundled example strategies — see `--help`.)
+and drive a family of runs over it. (`walkforward`, `mc`, and `generalize` also
+accept a legacy built-in form selected by `--strategy` instead of a `.json`
+path, for the engine's own bundled example strategies — see `--help`.)

 | Command | Purpose |
 |---|---|
@@ -512,7 +512,7 @@ pub(crate) struct GeneratedMc {
 /// Translate one `aura mc --strategy r-sma --real` invocation into its two generated
 /// documents: a `[std::sweep(argmax), std::walk_forward, std::monte_carlo]` process
 /// (the sweep enumerates the IS-refit survivor grid for the wf stage; the terminal
-/// monte_carlo stage pools the per-window OOS trade-R series and r-bootstraps E[R])
+/// monte_carlo stage pools the per-window OOS trade-R series and r-bootstraps `E[R]`)
 /// and a campaign running the fast/slow grid over one instrument under a single risk
 /// regime that carries the stop. Unlike `translate_walkforward` (which hardcodes
 /// `seed: 0`), `translate_mc` sets `campaign.seed = seed` (the mc `--seed`): the wf
@@ -1198,13 +1198,14 @@ fn run_unknown_harness_exits_two() {

 /// Property (#159 cut 2): `--strategy r-breakout` is a fully retired CLI token, on
 /// BOTH `sweep` and `walkforward` — indistinguishable from an unrecognized token
-/// (`bogus`), i.e. it falls through `strategy_from`'s catch-all into the plain
-/// usage error, not into a "valid-but-unsupported" branch (contrast
-/// `walkforward_unsupported_strategy_exits_2_naming_the_token`, which pins that
-/// shape for `momentum`). A regression that left `Strategy::RBreakout` parseable
-/// while only deleting its family builder would make this test's stderr start
-/// naming "r-breakout" specially instead of reading the generic `Usage: aura
-/// <verb> …` line — this is the negative that catches a half-finished retirement.
+/// (`bogus`). `--strategy` is now a plain `Option<String>` with no per-token
+/// dispatch, so a retired value carries nothing special: it flows into clap's
+/// generic usage path and out as exit 2 with the generic `aura: Usage: aura
+/// <verb> …` line, never a "valid-but-unsupported" message. A regression that
+/// re-taught the CLI to recognize "r-breakout" specially (rather than leaving it
+/// deleted) would make this test's stderr start naming "r-breakout" instead of
+/// reading the generic usage line — this is the negative that catches a
+/// half-finished retirement.
 #[test]
 fn sweep_and_walkforward_reject_retired_r_breakout_token_as_unrecognized() {
    for (args, verb) in [
@@ -1345,7 +1346,7 @@ fn generalize_grades_a_candidate_across_two_instruments() {

 /// Characterization pin (byte-identity anchor for the generalize dissolution,
 /// #210). The current `aura generalize` binds its protective stop as a grid axis
-/// (`r_sma_sweep_family` with `stop_open=true`); the dissolution rebinds the same
+/// (`blueprint_sweep_family` with `stop_open=true`); the dissolution rebinds the same
 /// stop through the risk-regime seam (`RiskRegime::Vol -> StopRule::Vol`). The
 /// sibling `generalize_grades_a_candidate_across_two_instruments` asserts shape
 /// only — `worst_case` and the per-instrument R floats are never checked — so a
@@ -1955,8 +1955,8 @@ mod tests {
        }
    }

-    /// Today's flat, hand-wired SMA-cross signal-quality harness (the
-    /// `sample_harness` wiring from `aura-cli`), with two recording sinks.
+    /// A flat, hand-wired SMA-cross signal-quality harness, with two
+    /// recording sinks.
    #[allow(clippy::type_complexity)]
    fn hand_wired_sma_cross_harness() -> (
        Harness,
@@ -2398,9 +2398,9 @@ mod tests {
    }

    /// A macd-like composite: one f64 input role `price`, three f64 outputs
-    /// (macd/signal/histogram), three params (fast/slow/signal lengths). Mirrors the
-    /// CLI `macd` composite's typed multi-output boundary, used to exercise
-    /// `derive_signature` on a composite.
+    /// (macd/signal/histogram), three params (fast/slow/signal lengths). A typed
+    /// multi-output boundary, used to exercise `derive_signature` on a
+    /// composite.
    fn macd_fixture() -> Composite {
        Composite::new(
            "macd",
@@ -333,8 +333,7 @@ mod tests {
    /// source role (`price`, → a synthetic source node), a composite reference
    /// (`sma_cross`, → a `composites` entry), a plain node (`Bias`), and a
    /// sink (`Recorder`, `output: vec![]`). A deliberately minimal serializer
-    /// fixture, independent of the CLI's built-in sample (`build_sample` in
-    /// aura-cli — a richer nested `signals` graph since cycle 0036), kept small so
+    /// fixture, kept small so
    /// this golden stays stable; the Recorder receiver is dropped because the
    /// model serializer never runs the graph.
    fn sample_root() -> Composite {
@@ -850,6 +850,10 @@ against an R-evaluator harness (the gross-R → net-R chain). On a non-R harness
 (exit 2)**, not a silent no-op — refuse-don't-guess. Negative cost rates are
 likewise rejected (exit 2) with a named diagnostic that identifies the offending
 flag. CLI ergonomics only; the cost-model graph and the R math are untouched.
+[HISTORY — the built-in `--harness` selector (its `sma`/`macd` non-R examples)
+was retired with the demos → blueprint-data (#159, cuts 1b-4); the cost-flag
+scoping rule survives on the `aura <verb> <blueprint.json>` r-sma run path over
+examples/r_*.json.]

 **Reframe (2026-06-23, #117 — exposure → bias, R as the signal-quality unit).**
 [HISTORY — its R spine survives into the 2026-06-28 contract; its Stage-2 currency /
@@ -937,6 +941,9 @@ harness fanning one bias into both `SimBroker` (legacy pip) and the RiskExecutor
 dedicated `aura-composites` crate, so `aura-engine`'s runtime dependency stays
 `aura-core`-only and `aura-std` is an `aura-engine` `[dev-dependencies]` (the graph
 stays acyclic).
+[HISTORY — the built-in `--harness` selector was retired with the demos →
+blueprint-data (#159, cuts 1b-4); `run` is now blueprint-driven — `aura run
+<blueprint.json>` over examples/r_*.json.]

 **Realization (2026-07-06 — the risk regime as a structural campaign axis, #210).**
 The `StopRule{Fixed,Vol}` structural axis is realized at the campaign-document
@@ -970,6 +977,9 @@ lengths), holding the stop and sizing fixed: `risk_budget` is R-invariant and
 1R**, so varying it would change what R *means* per member and break cross-member
 SQN comparability. Each swept member's manifest records the fixed R-defining params
 beside the floated knobs (reproducible from its own manifest, C18).
+[HISTORY — the built-in `--strategy` sweep surface was retired with the demos →
+blueprint-data (#159, cuts 1b-4); the rankable R sweep now runs as `aura sweep
+<blueprint.json> --axis …` over examples/r_sma_open.json.]

 **Realization (cycle 0067, #130 + #135).** **#130 (SQN100):** `RMetrics` gains
 `sqn_normalized = (mean_R/stdev_R)·√(min(n, 100))` — the n-normalized "SQN score"
@@ -980,6 +990,9 @@ stay byte-unchanged, and the field carries `#[serde(default)]` (C18). Below the
 `r_sma_sweep_family` persists each member's equity / exposure / r_equity under
 `runs/traces/<n>/<member_key>/` via the same `persist_traces_r` the single run uses;
 per-member `--trace` is symmetric across all three sweep strategies.
+[HISTORY — the built-in `--strategy` sweep triple (sma / momentum / r-sma) was
+retired with the demos → blueprint-data (#159, cuts 1b-4); the per-member
+`--trace` symmetry now lives on the `aura sweep <blueprint.json>` path.]

 **Realization (cycle 0068, #115 — position-event derive).** [The derivation
 survives as the **deploy / reconciliation** layer per the 2026-06-28 reframe — its
@@ -1858,7 +1871,7 @@ by key for determinism, C1); a family is its *first producer* — the deliberate
 step toward the programmable analysis meta-level (C21) **without** rebuilding the
 orchestration axes (that is its own later cycle). Name resolution is made a **total
 function** by the write-guard `TraceStore::ensure_name_free`, called once per tracing
-command (`run`/`run --harness macd`/`run --real` → Run; `sweep`/`mc`/`walkforward` → Family)
+command (`run`/`run <bp.json>`/`run --real` → Run; `sweep`/`mc`/`walkforward` → Family)
 to refuse cross-kind name reuse — so the one ambiguous on-disk state (a name used by
 both a run and a family) is unreachable. Every error path exits 2, never panics
 (C18/C10 refuse-don't-guess). Engine untouched (C9/C14): the whole change is
@@ -2362,7 +2375,11 @@ the project layout and docs-by-role are open (#192 context).
  path (its member lines carry no instrument/topology_hash/selection stamp and register no
  campaign document) — the built-in `--strategy` demo surface is #159's hard-wired-harness
  retirement target, not the dissolution's; for generalize/walkforward/mc the dissolved form
-  is `--strategy r-sma --real`. Milestone closed 2026-07-07 on a green end-to-end fieldtest
+  is `--strategy r-sma --real`. [HISTORY — #159 (cuts 1b-4) has since landed
+  (post-2026-07-07): the retirement target has been hit — the built-in
+  `--strategy` sweep/demo surface is retired and the inline `--strategy r-sma
+  --real` path no longer exists; the surviving form is `aura <verb>
+  <blueprint.json> --axis …` over examples/r_*.json.] Milestone closed 2026-07-07 on a green end-to-end fieldtest
  (0 bugs; behaviour preservation, campaign-substrate reach-through, and the risk-regime axis
  all confirmed); residual findings are discoverability/ergonomics follow-ups (#216 risk-axis
  discoverability, #217 verb knob asymmetry, #218 no-project store litter).
@@ -285,7 +285,7 @@ The harness's structural parameterization — which strategy, instrument(s), bro

 ### sweep
 **Avoid:** param-sweep, parameter sweep
-An orchestration axis varying tuning params (grid or random) within a fixed structure. The inner, param-tuning loop, distinct from the structural experiment matrix. On a loaded blueprint every open knob (`--list-axes`) is **required** — a subset is refused with the missing knob named; pin an unwanted knob with a single-value axis (`--axis name=<one-value>`), there is no default. `aura sweep --axis` takes the `--list-axes`-printed, root-composite-wrapped name (e.g. `graph.fast.length`) — not the raw `param_space` name (`fast.length`) that `graph introspect --params` and a campaign document's axes use; the CLI strips exactly one leading wrapper segment (#210). The `aura sweep` CLI verb is now thin sugar over the `campaign document` path — its blueprint form (`<bp.json> --real`) translates to a generated, content-addressed campaign run through the one executor (#210); `aura sweep --strategy …` stays the inline built-in-demo path (#159's hard-wired-harness retirement target).
+An orchestration axis varying tuning params (grid or random) within a fixed structure. The inner, param-tuning loop, distinct from the structural experiment matrix. On a loaded blueprint every open knob (`--list-axes`) is **required** — a subset is refused with the missing knob named; pin an unwanted knob with a single-value axis (`--axis name=<one-value>`), there is no default. `aura sweep --axis` takes the `--list-axes`-printed, root-composite-wrapped name (e.g. `graph.fast.length`) — not the raw `param_space` name (`fast.length`) that `graph introspect --params` and a campaign document's axes use; the CLI strips exactly one leading wrapper segment (#210). The `aura sweep` CLI verb is now thin sugar over the `campaign document` path — its blueprint form (`<bp.json> --real`) translates to a generated, content-addressed campaign run through the one executor (#210); the built-in `--strategy` sweep surface was retired by #159 (its hard-wired harnesses removed) — sweep now runs from a blueprint + `--axis`, and a retired `--strategy` token falls to the generic usage error.

 ### tap
 **Avoid:** —