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
This commit is contained in:
2026-07-08 11:12:22 +02:00
parent ee7001647c
commit 07a73fb66e
7 changed files with 39 additions and 22 deletions
+19 -2
View File
@@ -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).
+1 -1
View File
@@ -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:** —