Aura/docs/plans/0098-cli-clap-migration-iter1.md

# clap migration (iteration 1) — Implementation Plan

> **Parent spec:** `docs/specs/0098-cli-clap-gnu-compliance.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` skill to run
> this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Replace the hand-rolled argv parser in `aura-cli` with a `clap`
derive parser, delivering scoped `aura <sub> --help`, `--version`/`-V`, a
per-flag Options section, and native `--flag=value`/`--`/long-opt abbreviation —
behaviour-preserving on exit codes (the exit-code split is iteration 2).

**Architecture:** One root `Cli` with a `Command` subcommand enum; one `*Cmd`
struct per subcommand (the `Cmd` suffix avoids colliding with the existing
`RunArgs`/`McArgs` arg-types the untouched execution layer still uses). The four
dual-grammar subcommands (run/sweep/walkforward/mc) carry an optional
`[blueprint]` positional + the union of both branches' flags, dispatched
post-parse on a single-sourced `is_file()` predicate with flag-applicability
validation. Each handler converts its `*Cmd` into the exact argument shapes the
existing `run_*`/`emit_*`/`runs_*`/`reproduce_*` fns already accept — those fns
are untouched. clap parse errors exit 2 (matching today's usage-error=2); domain
refusals stay exit 2; reproduce-diverged stays exit 1.

**Tech Stack:** Rust 2024, `clap` 4 (derive), `aura-cli` binary.

---

**Files this plan creates or modifies:**

- Modify: `crates/aura-cli/Cargo.toml:12-42` — add `clap` dependency
- Modify: `crates/aura-cli/src/main.rs` — replace `fn main` dispatch + all
  `parse_*_args` with clap derive structs + typed handlers; delete `USAGE`,
  `COST_FLAGS_NOTE`, the global `--help` short-circuit, and the ten `usage()`
  closures. Keep every `run_*`/`emit_*`/`runs_*`/`reproduce_*` execution fn, the
  existing arg-types they consume (`RunArgs`, `McArgs`, `Stage1RGrid`, …), and
  every value helper (`parse_csv_list`, `parse_scalar_csv`, `parse_select`,
  `parse_param_cells`, `DataSource`, `Strategy`, `Selection`) verbatim.
- Modify: `crates/aura-cli/src/graph_construct.rs:127-237` — `graph build` /
  `graph introspect` become clap args under the `Graph` subcommand
- Test: `crates/aura-cli/tests/cli_run.rs` — new tests (`--version`,
  scoped-help, `--flag=value`, `--`) + renegotiate the broken help/usage pins
- Unchanged (must stay green): `crates/aura-cli/tests/cli_broken_pipe.rs`,
  `crates/aura-cli/tests/graph_construct.rs`

---

## Task 1: clap dependency + new-behaviour RED tests

**Files:**
- Modify: `crates/aura-cli/Cargo.toml:12-42`
- Test: `crates/aura-cli/tests/cli_run.rs`

- [ ] **Step 1: Add clap to Cargo.toml**

In `crates/aura-cli/Cargo.toml`, under `[dependencies]`, add:

```toml
# clap: the vetted standard argument parser. Adopted (C16 per-case review) to
# replace the hand-rolled argv parser + ten duplicated help surfaces with one
# declarative source, giving scoped --help, --version, --flag=value, and
# long-option abbreviation. Research-side CLI only (invariant 8): a dev-loop
# compile tax, never a frozen-artifact tax.
clap = { version = "4", features = ["derive"] }
```

- [ ] **Step 2: Verify clap resolves and the tree still builds**

Run: `cargo build --workspace`
Expected: PASS (clap and its transitive deps download and compile; no source
change yet, so the existing binary is unaffected).

- [ ] **Step 3: Write the four new-behaviour tests (RED)**

Append to `crates/aura-cli/tests/cli_run.rs`:

```rust
/// `--version` / `-V` surface the workspace version on stdout, exit 0 (GNU MUST;
/// today `aura --version` hits the catch-all → USAGE on stderr, exit 2).
#[test]
fn version_flag_prints_version_to_stdout_and_exits_zero() {
    for flag in ["--version", "-V"] {
        let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura"))
            .arg(flag)
            .output()
            .expect("spawn aura");
        assert_eq!(out.status.code(), Some(0), "{flag}: exit {:?}", out.status);
        let stdout = String::from_utf8_lossy(&out.stdout);
        assert!(stdout.contains("0.1.0"), "{flag} stdout: {stdout:?}");
    }
}

/// Subcommand help is SCOPED: `aura sweep --help` names sweep's own flags and is
/// NOT byte-identical to `aura run --help` (today both print the global blob, so
/// they are equal — this asserts the #131 uniform-help behaviour is retired).
#[test]
fn subcommand_help_is_scoped_not_uniform() {
    let sweep = std::process::Command::new(env!("CARGO_BIN_EXE_aura"))
        .args(["sweep", "--help"]).output().expect("spawn");
    let run = std::process::Command::new(env!("CARGO_BIN_EXE_aura"))
        .args(["run", "--help"]).output().expect("spawn");
    assert_eq!(sweep.status.code(), Some(0), "sweep --help exit");
    assert_eq!(run.status.code(), Some(0), "run --help exit");
    let sweep_out = String::from_utf8_lossy(&sweep.stdout);
    let run_out = String::from_utf8_lossy(&run.stdout);
    assert!(sweep_out.contains("--strategy"), "sweep help names its flags: {sweep_out:?}");
    assert_ne!(sweep_out, run_out, "per-subcommand help must be scoped, not uniform");
}

/// The GNU `--flag=value` equals form is accepted (today only space-separated).
#[test]
fn gnu_equals_form_is_accepted() {
    let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura"))
        .args(["run", "--harness=sma"]).output().expect("spawn");
    assert_eq!(out.status.code(), Some(0),
        "run --harness=sma should run; stderr: {}", String::from_utf8_lossy(&out.stderr));
}

/// The `--` end-of-options terminator is recognized (a bare `--` after the flags
/// is a no-op that still runs the default harness).
#[test]
fn double_dash_terminator_is_recognized() {
    let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura"))
        .args(["run", "--harness", "sma", "--"]).output().expect("spawn");
    assert_eq!(out.status.code(), Some(0),
        "run ... -- should run; stderr: {}", String::from_utf8_lossy(&out.stderr));
}
```

- [ ] **Step 4: Run the new tests to verify they FAIL (RED)**

Run each filter separately (one positional filter per invocation):

Run: `cargo test -p aura-cli --test cli_run version_flag_prints_version_to_stdout_and_exits_zero`
Expected: FAIL — exit is `Some(2)` (catch-all USAGE), not `Some(0)`.

Run: `cargo test -p aura-cli --test cli_run subcommand_help_is_scoped_not_uniform`
Expected: FAIL — `sweep --help` == `run --help` today (global blob), the
`assert_ne!` fails.

Run: `cargo test -p aura-cli --test cli_run gnu_equals_form_is_accepted`
Expected: FAIL — `--harness=sma` is not split today, `sma` is not matched, exit 2.

Run: `cargo test -p aura-cli --test cli_run double_dash_terminator_is_recognized`
Expected: FAIL — the trailing `--` is an unexpected token today, exit 2.

---

## Task 2: clap migration + pin renegotiation

The atomic migration (build cannot be green until `fn main` and all subcommands
are on clap together). Work Steps 1-7 as one coherent change, then the Step-8
build gate, then the Step-9/10 pin renegotiation, then the Step-11 suite gate.
Ends with the full suite green (the four Task-1 tests flip to PASS).

**Files:**
- Modify: `crates/aura-cli/src/main.rs`
- Modify: `crates/aura-cli/src/graph_construct.rs:127-237`
- Test: `crates/aura-cli/tests/cli_run.rs`

- [ ] **Step 1: Add clap imports and the root parser**

At the top of `crates/aura-cli/src/main.rs` add `use clap::{Parser, Subcommand, Args};`
and define the root (note: `*Cmd` names, to avoid colliding with the existing
`RunArgs`/`McArgs` arg-types):

```rust
#[derive(Parser)]
#[command(name = "aura", version, about = "A game engine for traders — research CLI")]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// Run a single backtest (built-in harness or a loaded blueprint).
    Run(RunCmd),
    /// Render a recorded run's trace to an HTML chart.
    Chart(ChartCmd),
    /// Emit / construct / introspect a graph.
    Graph(GraphCmd),
    /// Sweep a parameter grid over a strategy or a loaded blueprint.
    Sweep(SweepCmd),
    /// Walk-forward validation over a strategy or a loaded blueprint.
    Walkforward(WalkforwardCmd),
    /// Grade one candidate across multiple instruments.
    Generalize(GeneralizeCmd),
    /// Monte-Carlo over synthetic draws, an R-bootstrap, or a loaded blueprint.
    Mc(McCmd),
    /// List or inspect recorded run families.
    Runs(RunsCmd),
    /// Reproduce a recorded family by content id.
    Reproduce(ReproduceCmd),
}
```

`#[command(version)]` reads `CARGO_PKG_VERSION` (= workspace `0.1.0`) → `aura 0.1.0`.

- [ ] **Step 2: Define the non-dual-grammar subcommand `*Cmd` structs**

Add (flag inventory lifted verbatim from the current `parse_*` fns):

```rust
#[derive(Args)]
struct ChartCmd {
    /// The recorded run or family name to chart.
    name: String,
    /// Chart only the given tap.
    #[arg(long)] tap: Option<String>,
    /// Render stacked panels instead of an overlay.
    #[arg(long)] panels: bool,
}

#[derive(Args)]
struct GraphCmd {
    #[command(subcommand)]
    sub: Option<GraphSub>,
}

#[derive(Subcommand)]
enum GraphSub {
    /// Construct a graph from a stdin op-list.
    Build,
    /// Introspect a graph.
    Introspect(GraphIntrospectCmd),
}

#[derive(Args)]
struct GraphIntrospectCmd {
    #[arg(long)] vocabulary: bool,
    #[arg(long)] node: Option<String>,
    #[arg(long)] unwired: bool,
    #[arg(long)] content_id: bool,
}

#[derive(Args)]
struct GeneralizeCmd {
    #[arg(long)] strategy: Option<String>,
    /// Comma-separated instrument list (≥2 distinct, required).
    #[arg(long)] real: Option<String>,
    #[arg(long)] fast: Option<i64>,
    #[arg(long)] slow: Option<i64>,
    #[arg(long)] stop_length: Option<i64>,
    #[arg(long)] stop_k: Option<f64>,
    #[arg(long)] from: Option<i64>,
    #[arg(long)] to: Option<i64>,
    #[arg(long)] metric: Option<String>,
    #[arg(long)] name: Option<String>,
}

#[derive(Args)]
struct RunsCmd {
    #[command(subcommand)]
    sub: RunsSub,
}

#[derive(Subcommand)]
enum RunsSub {
    /// List recorded families.
    Families,
    /// Inspect one family, optionally ranked by a metric.
    Family {
        id: String,
        /// The literal keyword `rank`, if a ranking metric follows.
        rank_kw: Option<String>,
        /// The metric to rank by (only valid after `rank`).
        metric: Option<String>,
    },
}

#[derive(Args)]
struct ReproduceCmd {
    /// The family content id to reproduce.
    id: String,
}
```

- [ ] **Step 3: Define the four dual-grammar `*Cmd` structs**

Each carries an optional `[blueprint]` positional + the union of both branches'
flags. The three cost fields carry the #153 units note as `long_help` (see
Step 9 for the wrap-safe assertion):

```rust
#[derive(Args)]
struct RunCmd {
    /// A serialized signal blueprint (.json). An existing file selects the
    /// loaded-blueprint grammar; otherwise the built-in harness grammar.
    blueprint: Option<String>,
    /// Built-in harness: sma | macd | stage1-r (default sma).
    #[arg(long)] harness: Option<String>,
    /// Blueprint params (JSON scalar-cell array; .json mode).
    #[arg(long)] params: Option<String>,
    /// Blueprint seed (.json mode).
    #[arg(long)] seed: Option<u64>,
    #[arg(long)] real: Option<String>,
    #[arg(long)] from: Option<i64>,
    #[arg(long)] to: Option<i64>,
    #[arg(long)] trace: Option<String>,
    #[arg(long, long_help = "per-trade cost in price units. stage1-r only; charged in R as cost/|entry-stop|.")]
    cost_per_trade: Option<f64>,
    #[arg(long, long_help = "slippage multiplier on realized vol. stage1-r only.")]
    slip_vol_mult: Option<f64>,
    #[arg(long, long_help = "carry in price units per ENGINE cycle (not per day, not an overnight swap). stage1-r only.")]
    carry_per_cycle: Option<f64>,
}

#[derive(Args)]
struct SweepCmd {
    /// A loaded blueprint (.json); omit for the built-in --strategy grammar.
    blueprint: Option<String>,
    #[arg(long)] strategy: Option<String>,
    #[arg(long)] real: Option<String>,
    #[arg(long)] from: Option<i64>,
    #[arg(long)] to: Option<i64>,
    #[arg(long)] name: Option<String>,
    #[arg(long)] trace: Option<String>,
    #[arg(long)] fast: Option<String>,
    #[arg(long)] slow: Option<String>,
    #[arg(long)] stop_length: Option<String>,
    #[arg(long)] stop_k: Option<String>,
    #[arg(long)] channel: Option<String>,
    #[arg(long)] window: Option<String>,
    #[arg(long)] band_k: Option<String>,
    /// Blueprint sweep axis `<name>=<csv>` (repeatable; .json mode).
    #[arg(long)] axis: Vec<String>,
    /// List a loaded blueprint's sweepable axes and exit (.json mode, stands alone).
    #[arg(long)] list_axes: bool,
}

#[derive(Args)]
struct WalkforwardCmd {
    /// A loaded blueprint (.json); omit for the built-in --strategy grammar.
    blueprint: Option<String>,
    #[arg(long)] strategy: Option<String>,
    #[arg(long)] real: Option<String>,
    #[arg(long)] from: Option<i64>,
    #[arg(long)] to: Option<i64>,
    #[arg(long)] name: Option<String>,
    #[arg(long)] trace: Option<String>,
    #[arg(long)] fast: Option<String>,
    #[arg(long)] slow: Option<String>,
    #[arg(long)] stop_length: Option<String>,
    #[arg(long)] stop_k: Option<String>,
    #[arg(long)] select: Option<String>,
    /// Blueprint IS-refit axis `<name>=<csv>` (repeatable, ≥1 required; .json mode).
    #[arg(long)] axis: Vec<String>,
}

#[derive(Args)]
struct McCmd {
    /// A loaded blueprint (.json); omit for the built-in grammar.
    blueprint: Option<String>,
    #[arg(long)] strategy: Option<String>,
    #[arg(long)] real: Option<String>,
    #[arg(long)] from: Option<i64>,
    #[arg(long)] to: Option<i64>,
    #[arg(long)] name: Option<String>,
    #[arg(long)] trace: Option<String>,
    #[arg(long)] fast: Option<String>,
    #[arg(long)] slow: Option<String>,
    #[arg(long)] stop_length: Option<String>,
    #[arg(long)] stop_k: Option<String>,
    #[arg(long)] block_len: Option<usize>,
    #[arg(long)] resamples: Option<usize>,
    #[arg(long)] seed: Option<u64>,
    /// Number of synthetic draws (required; .json mode).
    #[arg(long)] seeds: Option<u64>,
}
```

- [ ] **Step 4: Single-source the dual-grammar predicate**

Add a helper near the `*Cmd` structs:

```rust
/// The dual-grammar discriminator: a first-positional that names an existing
/// `.json` file selects the loaded-blueprint branch. Single-sourced so the
/// four dual-grammar subcommands stay in lockstep.
fn is_blueprint_file(arg: &Option<String>) -> Option<&str> {
    arg.as_deref()
        .filter(|a| a.ends_with(".json") && std::path::Path::new(a).is_file())
}
```

- [ ] **Step 5a: Write the four dual-grammar handlers**

Each branches on `is_blueprint_file`, validates that no flag from the *other*
branch is set (usage error, exit 2, reusing existing message wording), enforces
the same intra-branch constraints the old `parse_*` fns did, and converts its
`*Cmd` fields into the exact argument shapes the existing execution fns accept.
The value-mapping is done inline with the existing helpers (`DataSource::from_choice`,
`Strategy`, `Stage1RGrid`, `Selection`, `parse_scalar_csv`, `parse_csv_list`,
`parse_select`, `parse_param_cells`) — on a bad enum/csv value, emit the existing
message + `exit(2)`. `RunCmd` example (the other three follow the same three-part
shape — branch, validate, convert-and-call — with their own flag sets and exec
fns, given explicitly below):

```rust
fn dispatch_run(a: RunCmd) {
    match is_blueprint_file(&a.blueprint) {
        Some(path) => {                              // .json branch
            if a.harness.is_some() {
                eprintln!("aura: --harness is not valid with a blueprint file");
                std::process::exit(2);
            }
            let doc = std::fs::read_to_string(path).unwrap_or_else(|e| {
                eprintln!("aura: {path}: {e}"); std::process::exit(2);
            });
            let signal = blueprint_from_json(&doc, &|t| std_vocabulary(t))
                .unwrap_or_else(|e| { eprintln!("aura: {path}: {e:?}"); std::process::exit(2); });
            let params = match a.params.as_deref() {
                Some(j) => parse_param_cells(j).unwrap_or_else(|m| { eprintln!("aura: {m}"); std::process::exit(2); }),
                None => Vec::new(),
            };
            let data = run_data_from(a.real.as_deref(), a.from, a.to);   // new thin adapter (Step 5c)
            let report = run_signal_stage1r(signal, &params, data, a.seed.unwrap_or(0));
            println!("{}", report.to_json());
        }
        None => {                                    // built-in branch
            if a.params.is_some() || a.seed.is_some() {
                eprintln!("aura: --params/--seed require a blueprint file");
                std::process::exit(2);
            }
            let run_args = run_args_from(&a).unwrap_or_else(|m| {   // new thin adapter (Step 5c)
                eprintln!("aura: {m}"); std::process::exit(2);
            });
            match run_dispatch(run_args) {
                Ok(report) => println!("{}", report.to_json()),
                Err(msg) => { eprintln!("aura: {msg}"); std::process::exit(2); }
            }
        }
    }
}
```

The other three dual-grammar handlers, explicitly:

- `dispatch_sweep(a: SweepCmd)`: `.json` branch → validate the `.json`-only rule
  (`--list-axes` must stand alone: if set and any other flag is present, the
  existing stand-alone-refusal message + exit 2), parse each `--axis`
  `name=csv` (empty/duplicate name → existing refusal + exit 2), then call
  `run_blueprint_sweep` (or the `--list-axes` probe path) exactly as the current
  `.json` arm does. Built-in branch → map `--strategy`/`--real`/grid flags via
  `Strategy`/`Stage1RGrid`/`DataSource::from_choice` and call `run_sweep`.
- `dispatch_walkforward(a: WalkforwardCmd)`: `.json` branch → `--axis` ≥1
  required (existing refusal + exit 2), `--select` via `parse_select`, call the
  blueprint walk-forward path (`DataSource::Synthetic`, as today). Built-in
  branch → map flags and call `run_walkforward`.
- `dispatch_mc(a: McCmd)`: `.json` branch → `--seeds` required and `>0` (existing
  refusal + exit 2), reject `--real`/`--from`/`--to` (unknown-in-this-branch →
  exit 2), call `run_blueprint_mc` (`DataSource::Synthetic`). Built-in branch →
  the `r_path` split (any of `--strategy`/grid/`--block-len`/`--resamples`/`--seed`
  ⇒ `run_mc_r_bootstrap`; otherwise `--name`/`--trace` ⇒ `run_mc`), reusing the
  exact `r_path` precedence and the "name flags rejected when r_path" refusal
  (exit 2).

For every intra-branch constraint (`--from`/`--to` require `--real`; cost flags
require an R-harness; an empty/duplicate axis) reuse the exact message string
the old `parse_*` fn emitted so the message-substring pins survive.

- [ ] **Step 5b: Write the five straight-through handlers**

```rust
fn dispatch_chart(a: ChartCmd) {
    emit_chart(&a.name, a.tap.as_deref(), if a.panels { ChartMode::Panels } else { ChartMode::Overlay });
}

fn dispatch_graph(a: GraphCmd) {
    match a.sub {
        None => print!("{}", render::render_html(&sample_blueprint())),
        Some(GraphSub::Build) => graph_construct::build_cmd(),
        Some(GraphSub::Introspect(i)) => graph_construct::introspect_cmd(i),   // Step 7
    }
}

fn dispatch_generalize(a: GeneralizeCmd) {
    // Convert to the existing generalize call: strategy must be stage1-r; --real
    // is a ≥2-distinct comma list; fast/slow/stop-length/stop-k all required;
    // metric default expectancy_r; name default generalize. Reuse the exact
    // refusal messages the old parse_generalize_args emitted (+ exit 2) for each
    // violated constraint, then call run_generalize(...).
    let (name, symbols, grid, metric, from_ms, to_ms) = generalize_args_from(&a)   // new thin adapter (Step 5c)
        .unwrap_or_else(|m| { eprintln!("aura: {m}"); std::process::exit(2); });
    run_generalize(&name, &symbols, &grid, &metric, from_ms, to_ms);
}

fn dispatch_runs(a: RunsCmd) {
    match a.sub {
        RunsSub::Families => runs_families(),
        RunsSub::Family { id, rank_kw, metric } => match (rank_kw.as_deref(), metric) {
            (None, None) => runs_family(&id, None),
            (Some("rank"), Some(m)) => runs_family(&id, Some(&m)),
            _ => { eprintln!("aura: usage: aura runs family <id> [rank <metric>]"); std::process::exit(2); }
        },
    }
}

fn dispatch_reproduce(a: ReproduceCmd) { reproduce_family(&a.id); }
```

- [ ] **Step 5c: Add the thin `*_from` adapters**

Add small private fns that convert a `*Cmd` into the argument shapes the existing
exec fns accept, reusing the existing value helpers. These are NEW (they replace
the body of the old `parse_*_args`, minus the argv tokenizing clap now owns):

- `run_data_from(real: Option<&str>, from: Option<i64>, to: Option<i64>) -> RunData`
  — mirror the old `--real`/`--from`/`--to` resolution (`--from`/`--to` require
  `--real`; on violation emit the existing message + exit 2).
- `run_args_from(a: &RunCmd) -> Result<RunArgs, String>` — build the existing
  `RunArgs` (the type `run_dispatch` consumes) from the built-in-branch fields,
  applying the harness-enum map and the cost-flags-require-R-harness /
  non-negative-rate checks with the existing message strings.
- `generalize_args_from(a: &GeneralizeCmd) -> Result<(String, Vec<String>, Stage1RGrid, String, Option<i64>, Option<i64>), String>`
  — the old `parse_generalize_args` body minus tokenizing.

Keep the `Err(String)` message text identical to the old closures so the pins in
Step 10 survive.

- [ ] **Step 6: Rewrite `fn main`; delete the old parser surface**

Replace the body of `fn main` (keep the SIGPIPE reset verbatim) with:

```rust
fn main() {
    #[cfg(unix)]
    unsafe { libc::signal(libc::SIGPIPE, libc::SIG_DFL); }   // unchanged
    match Cli::parse().command {
        Command::Run(a)         => dispatch_run(a),
        Command::Chart(a)       => dispatch_chart(a),
        Command::Graph(a)       => dispatch_graph(a),
        Command::Sweep(a)       => dispatch_sweep(a),
        Command::Walkforward(a) => dispatch_walkforward(a),
        Command::Generalize(a)  => dispatch_generalize(a),
        Command::Mc(a)          => dispatch_mc(a),
        Command::Runs(a)        => dispatch_runs(a),
        Command::Reproduce(a)   => dispatch_reproduce(a),
    }
}
```

Delete: the global `--help`/`-h` short-circuit; the `USAGE` const; the
`COST_FLAGS_NOTE` const; every local `usage()` closure inside the old
`parse_*_args` fns; and the old `parse_*_args` fns themselves (`parse_run_args`,
`parse_blueprint_run_args`, `parse_chart_args`, `parse_sweep_args`,
`parse_sweep_blueprint_args`, `parse_walkforward_args`,
`parse_walkforward_blueprint_args`, `parse_generalize_args`, `parse_mc_args`,
`parse_mc_blueprint_args`, `parse_nonneg_rate`). Keep the *existing arg-types*
they fed (`RunArgs`, `McArgs`, `Stage1RGrid`, `Selection`, `DataSource`,
`Strategy`) and the *value helpers* (`parse_csv_list`, `parse_scalar_csv`,
`parse_select`, `parse_param_cells`) — the adapters in Step 5c reuse them.

- [ ] **Step 7: Migrate `graph build` / `graph introspect`**

In `graph_construct.rs`, `build_cmd()` keeps its body verbatim. Change
`introspect_cmd` to take the parsed `GraphIntrospectCmd` instead of `rest:
&[&str]`: replace its hand-parsing of `--vocabulary`/`--node`/`--unwired`/
`--content-id` with reading the struct fields, and validate that exactly one is
set (reuse the existing usage message + exit 2 if not). The stdin op-list reading
and the execution bodies are unchanged.

- [ ] **Step 8: Build gate**

Run: `cargo build --workspace`
Expected: PASS (0 errors).

Run: `cargo clippy --workspace --all-targets -- -D warnings`
Expected: PASS (0 warnings — no dead code, all structs/handlers wired).

- [ ] **Step 9: Renegotiate the help pins**

In `crates/aura-cli/tests/cli_run.rs`:

Replace `per_subcommand_help_is_uniform_stdout_exit_zero` (#131) — it asserts
help is UNIFORM, which the migration retires — with a scoped-help assertion:

```rust
#[test]
fn per_subcommand_help_is_scoped_stdout_exit_zero() {
    for sub in ["run", "chart", "sweep", "walkforward", "mc", "graph", "runs"] {
        for help in ["--help", "-h"] {
            let out = std::process::Command::new(env!("CARGO_BIN_EXE_aura"))
                .args([sub, help]).output().expect("spawn");
            assert_eq!(out.status.code(), Some(0), "{sub} {help} exit");
            assert!(!out.stdout.is_empty(), "{sub} {help} stdout empty");
            assert!(out.stderr.is_empty(), "{sub} {help} stderr not empty: {:?}",
                String::from_utf8_lossy(&out.stderr));
        }
    }
}
```

`run_help_surfaces_cost_flag_units_note` (#153) — clap wraps `long_help` at the
render width, which can split a multi-word substring across lines. Make the pin
wrap-robust: assert `run --help` stdout contains the single tokens `"ENGINE"`,
`"cycle"`, and `"stage1-r"` (clap does not hyphenate or split a single word),
rather than the multi-word `"per ENGINE cycle"`. Rewrite the two assertions to
those single-word substrings.

`help_flag_prints_usage_to_stdout_and_exits_zero` — `aura --help` now prints the
top-level Commands list to stdout, exit 0. Keep exit 0; change the assertion to
stdout contains `"run"` (still listed as a command) and change any
`contains("usage")` (lowercase) to `contains("Usage")` (clap capitalizes). Keep
the "unknown subcommand exits 2" sub-assertion.

- [ ] **Step 10: Renegotiate the generic usage-substring pins**

clap parse errors go to stderr with a capitalized `"Usage:"` line, not the old
lowercase `"usage:"`. For each test asserting stderr `contains("usage")` on a
PARSE error, change the substring to `"Usage"` (capital); the exit-2 expectation
is PRESERVED. Affected (assert exit 2 + `"usage"`):

- `run_with_trailing_token_is_strict_and_exits_two` → `"Usage"`
- `no_args_prints_usage_and_exits_two` (bare `aura`: clap errors "subcommand
  required" → stderr `"Usage"`, exit 2, stdout empty) → `"Usage"`
- `sweep_with_trailing_token_is_strict_and_exits_two` → `"Usage"`

For tests asserting an AURA-SPECIFIC message (from a post-parse validation, NOT
`"usage"`) the message is PRESERVED, so NO change is needed — verify each still
passes:
`mc_rejects_real_flag_with_usage_exit_2` (`"--real"`),
`family_window_flag_without_real_refuses_with_usage_exit_2` (cmd + `"--real"`),
`run_cost_flag_on_non_r_harness_is_refused_exit_2` (`"R-evaluator harness"`),
`run_negative_cost_per_trade_refused_non_negative_exit_2` (`"must be non-negative"`),
the `generalize_refuses_*` family, the axis refusals, `aura_sweep_list_axes_rejects_other_flags`,
and the domain-refusal message pins (`"no local data"`, `"no recorded geometry"`,
`"no recorded run or family"`, `"run has no tap named"`, `"UnknownNodeType"`).
For `runs_list_and_rank_are_retired_and_exit_two` / `runs_bare_subcommand_is_strict_and_exits_two`:
`runs list` / `runs rank <m>` / bare `runs` are now clap "unknown/ missing
subcommand" errors → exit 2 preserved; adjust any `"usage"` substring to
`"Usage"` (or drop the substring assertion, keeping exit 2).

- [ ] **Step 11: Full-suite gate**

Run: `cargo test --workspace`
Expected: PASS — every test green, including the four Task-1 tests (now GREEN),
the renegotiated help/usage pins, and all preserved-message + happy-path pins.
`cli_broken_pipe.rs` and `graph_construct.rs` stay green untouched.

Run: `cargo clippy --workspace --all-targets -- -D warnings`
Expected: PASS.

---

## Notes for the executor

- **Task 2 is the atomic migration** — the build cannot be green until `fn main`
  and all subcommands are on clap together (build-atomicity). Steps 1-7 are one
  coherent change; the first gate is the Step-8 build, not per-sub.
- **The execution layer is untouched.** Only arg-plumbing changes: the `*Cmd`
  structs (clap) + the handlers + the thin `*_from` adapters. Every
  `run_*`/`emit_*`/`runs_*`/`reproduce_*` body and every existing arg-type/value
  helper stays verbatim. If a step tempts you to change an exec-fn body, stop.
- **Exit codes are behaviour-preserved.** clap parse errors exit 2; every domain
  refusal and post-parse validation stays exit 2; reproduce-diverged stays exit
  1. The exit-code split (2=usage/1=runtime) is iteration 2, out of scope here.
- **Preserve message substrings verbatim** where a test pins them — reuse the
  exact strings the old `parse_*`/refusal paths emitted.