# Exit-code split (iteration 2) — 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:** Apply the clean exit-code partition (#175 deviation #8): runtime
failures exit 1, usage errors exit 2, with no same-class inconsistency — on top
of the clap migration (iteration 1, behaviour-preserving on exit codes).

**Architecture:** The partition rule (attribution principle): **exit 1 =
runtime** — the command line was well-formed but the environment / recorded state
it needs is missing, or piped stdin data is bad; **exit 2 = usage** — something
about the command-line arguments (including a named file's content) is wrong or
inapplicable. Only the "missing environment/recorded state" `exit(2)` sites in
the dispatch handlers + execution fns flip to `exit(1)`; every argument-fault
site (clap parse errors, post-parse validations, malformed/open argv blueprint
files, invalid flag values, unsupported combinations, unknown axis/metric names)
stays `exit(2)`. `reproduce`-diverged stays `exit(1)`. No parser structure
changes.

**Tech Stack:** Rust 2024, `aura-cli` binary — `crates/aura-cli/src/main.rs`,
`crates/aura-cli/src/graph_construct.rs`, `crates/aura-cli/tests/cli_run.rs`.

---

**Files this plan creates or modifies:**

- Modify: `crates/aura-cli/src/main.rs` — flip the classified RUNTIME
  `std::process::exit(2)` sites to `exit(1)`; usage sites unchanged
- Modify: `crates/aura-cli/src/graph_construct.rs:127-240` — stdin op-script
  content + stdin-read I/O → `exit(1)`; argv-flag errors stay `exit(2)`
- Test: `crates/aura-cli/tests/cli_run.rs` — flip the runtime domain-refusal
  exit pins (`Some(2)`→`Some(1)`), fix the hidden guard/match arms, add the
  partition property test
- Unchanged (must stay green): `crates/aura-cli/tests/cli_broken_pipe.rs`
  (SIGPIPE), `crates/aura-cli/tests/graph_construct.rs` (no exit-integer pins)

---

## Task 1: Renegotiate the runtime exit pins to 1 (RED)

Flip the tests first — they go RED because the code still exits 2. Task 2 flips
the code to make them GREEN. The message substrings are UNCHANGED; only the exit
integer flips.

**Files:**
- Test: `crates/aura-cli/tests/cli_run.rs`

- [ ] **Step 1: Flip the direct runtime exit-2 pins to exit-1**

In `crates/aura-cli/tests/cli_run.rs`, change `assert_eq!(out.status.code(),
Some(2), ...)` to `Some(1)` in these tests (locate by name; the message
`.contains(...)` assertions stay verbatim):

- `run_real_no_geometry_symbol_refuses_with_exit_2` — the `Some(2)` on the "no
  recorded geometry for symbol 'NONEXISTENT'" refusal → `Some(1)`
- `run_real_refusal_names_no_authored_floor` — the `Some(2)` → `Some(1)`
- `run_real_no_geometry_symbol_emits_no_stdout_report` — the `Some(2)` → `Some(1)`
- `chart_emits_self_contained_html_for_a_persisted_run` — the missing-run
  sub-assertion `Some(2)` → `Some(1)`
- `chart_tap_nonexistent_on_run_refuses_with_exit_2` — `Some(2)` → `Some(1)`
  (keeps "run has no tap named 'nope'", "available:")
- `chart_unknown_name_refuses_with_exit_2_and_message` — `Some(2)` → `Some(1)`
  (keeps "no recorded run or family 'ghost'")
- `sweep_real_no_geometry_symbol_refuses_with_exit_2` — `Some(2)` → `Some(1)`
  (keeps "no recorded geometry")
- `trace_name_collision_across_kinds_is_refused` — BOTH `Some(2)` → `Some(1)`

(Optional but consistent: rename these tests dropping the `_exit_2` suffix or
leaving it — a rename is not required and risks a filter miss; leave the names,
only the integer changes.)

- [ ] **Step 2: Fix the hidden guard / match arms (drift-prone)**

These tests branch on `code()` and would silently misbehave if left at `Some(2)`:

- `run_real_sidecar_symbol_never_hits_the_pip_refusal` — the
  `match out.status.code() { Some(2) => {..."no local data for symbol
  'EURUSD'"...}, other => panic!(...) }`: change the `Some(2)` arm to `Some(1)`
  (a no-data host now exits 1; otherwise the arm misses and hits the panic).
- `run_real_sidecar_index_pip_reaches_the_emitted_manifest` — the skip-guard
  `if out.status.code() == Some(2)` on "no local data for symbol 'GER40'":
  change to `== Some(1)`.
- `run_real_nonvetted_symbol_resolves_pip_from_sidecar` — the skip-guard `if
  out.status.code() == Some(2)` on "no recorded geometry" / "no local data":
  change to `== Some(1)`.

- [ ] **Step 3: Add the partition property test**

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

```rust
/// The exit-code partition (#175 iteration 2, deviation #8): a USAGE error (a
/// malformed command line) exits 2; a RUNTIME failure (a well-formed command
/// whose needed data/state is missing) exits 1. Pins the partition as a property.
#[test]
fn exit_codes_partition_usage_two_from_runtime_one() {
    // usage: an unknown flag is a command-line error → exit 2
    let usage = std::process::Command::new(env!("CARGO_BIN_EXE_aura"))
        .args(["run", "--bogus"]).output().expect("spawn");
    assert_eq!(usage.status.code(), Some(2),
        "unknown flag is a usage error → 2; stderr: {}", String::from_utf8_lossy(&usage.stderr));
    // runtime: a well-formed command whose symbol has no recorded data → exit 1
    let runtime = std::process::Command::new(env!("CARGO_BIN_EXE_aura"))
        .args(["run", "--real", "NONEXISTENT"]).output().expect("spawn");
    assert_eq!(runtime.status.code(), Some(1),
        "no data for a valid command is a runtime failure → 1; stderr: {}",
        String::from_utf8_lossy(&runtime.stderr));
}
```

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

Run: `cargo test -p aura-cli --test cli_run exit_codes_partition_usage_two_from_runtime_one`
Expected: FAIL — the runtime arm gets `Some(2)` (code still exits 2), not `Some(1)`.

Run: `cargo test -p aura-cli --test cli_run run_real_no_geometry_symbol_refuses`
Expected: FAIL — `Some(2)` received where `Some(1)` now asserted.

---

## Task 2: Flip the runtime code sites to exit 1 (GREEN)

Change `std::process::exit(2)` to `std::process::exit(1)` at the classified
RUNTIME sites in `main.rs` and `graph_construct.rs`. Locate each by its enclosing
fn + message string (line numbers drift as edits land). USAGE sites are NOT
touched. After this, the Task-1 tests go green.

**Files:**
- Modify: `crates/aura-cli/src/main.rs`
- Modify: `crates/aura-cli/src/graph_construct.rs`

- [ ] **Step 1: Flip the missing-data / missing-recorded-state sites (main.rs)**

Change `exit(2)` → `exit(1)` at each (by fn + message):
- `no_real_data` — `"no local data for symbol '{symbol}' …"`
- `pip_or_refuse` — `"no recorded geometry for symbol '{symbol}' …"`
- `emit_chart` — the store-read failure, the tap failure ("run has no tap
  named"), the read_family failure, the build_comparison failure, and `"no
  recorded run or family '{name}'…"` (all five exit sites in `emit_chart`)
- `runs_families` — the `load_family_members` failure
- `runs_family` — the `load_family_members` failure

- [ ] **Step 2: Flip the name-collision sites (main.rs)**

Change `exit(2)` → `exit(1)` at every `ensure_name_free` refusal (the `"{e}"`
after `ensure_name_free(...)`), in: `run_sample`, `run_sample_real`, `run_sweep`,
`run_walkforward`, `run_mc`, `run_macd`, `run_stage1_r`. (These are the
trace-name-collision-across-kinds class the spec lists as runtime.)

- [ ] **Step 3: Flip the reproduce missing/corrupted-stored-state sites (main.rs)**

Change `exit(2)` → `exit(1)` in `reproduce_family_in` at: `load_family_members`
failure, `"no such family '{id}'"`, `"family member has no topology_hash; not a
generated run"`, the `get_blueprint` failure, `"blueprint {hash} missing from
store"`, `"stored blueprint {hash} does not parse: {e:?}"`; and in
`point_from_params` at `"manifest is missing param {}"`. (These are missing /
corrupt content-addressed store state = runtime.) LEAVE `reproduce_family`'s
diverged-member `exit(1)` unchanged (already 1).

- [ ] **Step 4: Normalize the persist-write class to 1 (main.rs)**

Change `exit(2)` → `exit(1)` at every persist WRITE failure so the whole class is
consistent (`run_generalize`'s `"failed to persist family"` is already `exit(1)`
— leave it; the others flip to match):
- `persist_traces` — `"trace persist failed: {e}"` (TraceStore::write)
- `persist_traces_r` — `"trace persist failed: {e}"` (TraceStore::write)
- `run_sweep` — `append_family` failure
- `run_walkforward` — `append_family` failure
- `run_mc` — `append_family` failure
- `run_blueprint_sweep` — `put_blueprint` and `append_family` failures
- `run_blueprint_walkforward` — `put_blueprint` and `append_family` failures
- `run_blueprint_mc` — `put_blueprint` and `append_family` failures

- [ ] **Step 5: Flip the stdin runtime sites (graph_construct.rs)**

Change `exit(2)` → `exit(1)` where the fault is stdin op-script CONTENT or a
stdin-read I/O failure; LEAVE argv-flag usage errors at `exit(2)`:
- `build_cmd` — `"reading stdin: {e}"` (stdin-read I/O) → 1
- `build_cmd` — `build_from_str` `"{msg}"` (op-script content) → 1
- `introspect_cmd` — the two `"reading stdin: {e}"` (stdin-read I/O) → 1
- `introspect_cmd` — `introspect_unwired` `"{m}"` (op-script content) → 1
- `introspect_cmd` — `build_from_str` `"{m}"` for `--content-id` (op-script
  content) → 1
- LEAVE at `exit(2)`: `introspect_cmd` — `"usage: aura graph introspect …"`
  (argv-flag error) and `introspect_node` `"{m}"` for `--node <T>` (an invalid
  argv flag value = usage).

- [ ] **Step 6: Confirm the usage sites are untouched**

Verify (read, do not edit) that these STAY `exit(2)`: every `dispatch_*`
argument-applicability guard; `run_data_from` (`--from`/`--to` without `--real`);
`run_args_from` (harness / cost-flags-require-R / non-negative / window);
`generalize_args_from` (required knobs / ≥2 instruments / duplicate / strategy);
`dispatch_runs` rank grammar; all the dual-grammar blueprint FILE read/parse
sites in the four `.json` branches (`read_to_string` + `blueprint_from_json` in
`dispatch_run`/`dispatch_sweep`/`dispatch_walkforward`/`dispatch_mc` — a named
argv file's bad content is a usage error, staying 2); the applicability refusals
(walkforward-form-for-strategy, mc-requires-closed-blueprint, unknown `--axis`,
invalid `--metric`/`--select`/`--strategy`).

- [ ] **Step 7: Build + full-suite gate**

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

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

Run: `cargo test --workspace`
Expected: PASS — the Task-1 flipped pins + partition property test now GREEN; the
usage-error pins unchanged and green; `cli_broken_pipe.rs` and
`graph_construct.rs` green untouched.

---

## Notes for the executor

- **Behaviour change, pinned.** This iteration deliberately changes observable
  exit codes for runtime failures (2→1). Task 1 flips the pins RED-first; Task 2
  flips the code GREEN. Do not "fix" a red Task-1 pin by reverting it — the red
  is the point until Task 2 lands.
- **Attribution rule for any site not listed:** if the user must fix the COMMAND
  LINE (a flag value, an unsupported combination, a named file's content) → stays
  `exit(2)`; if the command was well-formed but the ENVIRONMENT/recorded state is
  missing or the STDIN data is bad → `exit(1)`.
- **The dual-grammar quartet stays in lockstep:** the four `.json`-branch file
  read/parse sites are all usage (exit 2) — do not flip any one of them.
- **No message-string edits.** Only the exit integer changes; every `.contains()`
  substring pin stays satisfied. The mixed "Usage:"/"usage:" casing is left as-is
  this iteration (a separate cosmetic-polish concern).