From d7c935dd77f1d9745a8d693d04ffd6c24e41e4b4 Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 2 Jul 2026 12:59:36 +0200 Subject: [PATCH] audit: cycle 0101 tidy (drift-clean after one ledger alignment) Architect review of 8814e295..HEAD. What holds: the cosmetic-only claim is verified (every -/+ pair in the code diff is a string literal; no exit(), channel, or control-flow byte moved; the C14 usage=2/runtime=1 partition preserved at every touched site); grep gates exact (zero lowercase usage: literals, 11 'Usage: aura' source lines = 10 edited + the pre-conforming run_args_from); fieldtests corpus and refusal diagnostics byte-identical. The recorded spec deviation (3 additive house-style pins) strengthens coverage over a real pin gap and is decision-logged on the issue. Regression: cargo build rc=0, cargo test --workspace rc=0 (cli_run 133 passed / 0 failed), clippy -D warnings rc=0, doc build rc=0. No baselines exist to move, so nothing to ratify. Drift resolved in this commit: the C14 ledger note still described the casing normalization as deferred after #179 landed - rewritten to record the landed house style (usage lines 'Usage: aura ...', refusal diagnostics deliberately unprefixed). Ephemeral cycle artifacts removed per convention: spec 0101, plan 0101. refs #179 --- docs/design/INDEX.md | 4 +- docs/plans/0101-normalize-cli-usage-casing.md | 223 ------------------ docs/specs/0101-normalize-cli-usage-casing.md | 210 ----------------- 3 files changed, 3 insertions(+), 434 deletions(-) delete mode 100644 docs/plans/0101-normalize-cli-usage-casing.md delete mode 100644 docs/specs/0101-normalize-cli-usage-casing.md diff --git a/docs/design/INDEX.md b/docs/design/INDEX.md index 1846079..c485e06 100644 --- a/docs/design/INDEX.md +++ b/docs/design/INDEX.md @@ -1087,7 +1087,9 @@ needed environment / recorded state is missing, or bad piped stdin data. The fou dual-grammar subcommands (run/sweep/walkforward/mc) keep both grammars under one token via an optional `[blueprint]` positional + a post-parse `is_file()` dispatch; the execution layer is unchanged (arg-plumbing via thin `*_from` -adapters). Error-message casing normalization was deferred (#179); the +adapters). Error-message casing is normalized to the clap house style — +every hand-rolled usage line reads `Usage: aura …` (#179, cycle 0101); +refusal diagnostics stay unprefixed (diagnostics are not usage lines). The machine-first help surface (JSON/manifest help, stdin op-scripts) stays on the #157/C21 track, not this cycle (settled as human/GNU convention compliance). diff --git a/docs/plans/0101-normalize-cli-usage-casing.md b/docs/plans/0101-normalize-cli-usage-casing.md deleted file mode 100644 index 805305b..0000000 --- a/docs/plans/0101-normalize-cli-usage-casing.md +++ /dev/null @@ -1,223 +0,0 @@ -# Normalize CLI usage-message casing — Implementation Plan - -> **Parent spec:** `docs/specs/0101-normalize-cli-usage-casing.md` -> -> **For agentic workers:** REQUIRED SUB-SKILL: use the -> `implement` skill to run this plan. Steps use `- [ ]` -> checkboxes for tracking. - -**Goal:** Normalize every hand-rolled CLI usage line to the single house -style `Usage: aura …` (10 literal edits) and flip the one -casing-sensitive test pin in lockstep — cosmetic only, no behaviour -change (issue #179). - -**Architecture:** All edits are byte-substitutions inside existing -string literals on existing exit-2 usage paths; emission channels -(stderr via the `aura: ` convention), exit codes, and control flow stay -byte-identical. The lockstep unit is indivisible: the mc built-in -literal (site #6) and the `cli_run.rs` pin must move together or the -suite goes red, so this plan is one task. - -**Tech Stack:** `crates/aura-cli` (clap v4 derive CLI), Rust string -literals, `cargo test` integration suite `cli_run.rs`. - ---- - -**Files this plan creates or modifies:** - -- Modify: `crates/aura-cli/src/graph_construct.rs:191` — site #1 casing flip -- Modify: `crates/aura-cli/src/main.rs:3991,4187,4272,4288,4346,4386,4424,4465,4503` — sites #2–#10 -- Test: `crates/aura-cli/tests/cli_run.rs:1409` — the single casing-sensitive pin flips lowercase `"usage"` → `"Usage"` - -**Off-limits (do not touch):** every other string in `crates/aura-cli` -(refusal diagnostics, the already-conforming `run_args_from` literal at -`main.rs:4012`), all other test bytes, and the `fieldtests/` corpus -(its old exact-equality usage pins are out-of-workspace by design and -stay byte-identical). - ---- - -### Task 1: House-style normalization + lockstep pin flip - -**Files:** -- Modify: `crates/aura-cli/src/graph_construct.rs:191` -- Modify: `crates/aura-cli/src/main.rs:3991,4187,4272,4288,4346,4386,4424,4465,4503` -- Test: `crates/aura-cli/tests/cli_run.rs:1409` - -Each edit below is exact: `old` is the complete current line (verified -unique in its file), `new` is the complete replacement line. Only the -shown bytes change. Note sites #7 and #9 contain a Unicode ellipsis -(`…`) inside `[--axis …]` — preserve it verbatim. - -- [ ] **Step 1: Site #1 — `graph_construct.rs:191` (`introspect_cmd`)** - -old: -```rust - "aura: usage: aura graph introspect --vocabulary | --node | --unwired | --content-id" -``` -new: -```rust - "aura: Usage: aura graph introspect --vocabulary | --node | --unwired | --content-id" -``` - -- [ ] **Step 2: Site #2 — `main.rs:3991` (`run_data_from`, let-binding)** - -old: -```rust - let usage = "usage: aura run [--params ] [--seed ] [--real [--from ] [--to ]]"; -``` -new: -```rust - let usage = "Usage: aura run [--params ] [--seed ] [--real [--from ] [--to ]]"; -``` - -- [ ] **Step 3: Site #3 — `main.rs:4187` (`dispatch_run`, inline eprintln, verbatim twin of #2 with baked `aura: `)** - -old: -```rust - eprintln!("aura: usage: aura run [--params ] [--seed ] [--real [--from ] [--to ]]"); -``` -new: -```rust - eprintln!("aura: Usage: aura run [--params ] [--seed ] [--real [--from ] [--to ]]"); -``` - -- [ ] **Step 4: Site #4 — `main.rs:4272` (`dispatch_runs`)** - -old: -```rust - eprintln!("aura: usage: aura runs family [rank ]"); -``` -new: -```rust - eprintln!("aura: Usage: aura runs family [rank ]"); -``` - -- [ ] **Step 5: Site #5 — `main.rs:4465` (`dispatch_mc`, blueprint branch; gains the program name)** - -old: -```rust - let usage = "usage: mc --seeds [--name ]"; -``` -new: -```rust - let usage = "Usage: aura mc --seeds [--name ]"; -``` - -- [ ] **Step 6: Site #6 — `main.rs:4503` (`dispatch_mc`, built-in branch; BOTH ` | `-separated alternatives gain the program name)** - -old: -```rust - let usage = || "usage: mc [--name |--trace ] | mc --strategy r-sma [--real [--from ] [--to ]] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--block-len ] [--resamples ] [--seed ]".to_string(); -``` -new: -```rust - let usage = || "Usage: aura mc [--name |--trace ] | aura mc --strategy r-sma [--real [--from ] [--to ]] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--block-len ] [--resamples ] [--seed ]".to_string(); -``` - -- [ ] **Step 7: Site #7 — `main.rs:4288` (`dispatch_sweep`, blueprint branch; bare → prefixed; keep the `…` byte)** - -old: -```rust - let usage = || "sweep --axis = [--axis …] [--name | --trace ] [--real [--from ] [--to ]]".to_string(); -``` -new: -```rust - let usage = || "Usage: aura sweep --axis = [--axis …] [--name | --trace ] [--real [--from ] [--to ]]".to_string(); -``` - -- [ ] **Step 8: Site #8 — `main.rs:4346` (`dispatch_sweep`, built-in branch; bare → prefixed)** - -old: -```rust - let usage = || "sweep [--strategy ] [--real [--from ] [--to ]] [--name | --trace ] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--channel ] [--window ] [--band-k ]".to_string(); -``` -new: -```rust - let usage = || "Usage: aura sweep [--strategy ] [--real [--from ] [--to ]] [--name | --trace ] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--channel ] [--window ] [--band-k ]".to_string(); -``` - -- [ ] **Step 9: Site #9 — `main.rs:4386` (`dispatch_walkforward`, blueprint branch; bare → prefixed; keep the `…` byte)** - -old: -```rust - let usage = || "walkforward --axis = [--axis …] [--select ] [--name ]".to_string(); -``` -new: -```rust - let usage = || "Usage: aura walkforward --axis = [--axis …] [--select ] [--name ]".to_string(); -``` - -- [ ] **Step 10: Site #10 — `main.rs:4424` (`dispatch_walkforward`, built-in branch; bare → prefixed)** - -old: -```rust - let usage = || "walkforward [--strategy ] [--real [--from ] [--to ]] [--name | --trace ] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--select ]".to_string(); -``` -new: -```rust - let usage = || "Usage: aura walkforward [--strategy ] [--real [--from ] [--to ]] [--name | --trace ] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--select ]".to_string(); -``` - -- [ ] **Step 11: Lockstep pin flip — `cli_run.rs:1409` (test `mc_rejects_real_flag_with_usage_exit_2`)** - -Only the predicate substring flips; the panic-message argument keeps its -lowercase "usage" verbatim. - -old: -```rust - assert!(stderr.contains("usage"), "mc --real stderr must carry usage: {stderr:?}"); -``` -new: -```rust - assert!(stderr.contains("Usage"), "mc --real stderr must carry usage: {stderr:?}"); -``` - -- [ ] **Step 12: Build gate** - -Run: `cargo build --workspace` -Expected: clean compile, 0 errors, 0 warnings introduced. - -- [ ] **Step 13: Targeted pin test** - -Run: `cargo test -p aura-cli --test cli_run mc_rejects_real_flag_with_usage_exit_2` -Expected: `1 passed; 0 failed` (exactly one test matches the filter). - -- [ ] **Step 14: Full-suite gate** - -Run: `cargo test --workspace` -Expected: green, 0 failures across all targets. Any failure other than -a test this plan did not touch going red means an edit strayed outside -the normative table — fix the edit, never a pin. - -- [ ] **Step 15: Lint gate** - -Run: `cargo clippy --workspace --all-targets -- -D warnings` -Expected: clean, 0 warnings. - -- [ ] **Step 16: Literal grep gates** - -Run: `grep -rn '"usage:' crates/aura-cli/src/` -Expected: no output (exit 1 — zero hits). - -Run: `grep -rn 'aura: usage:' crates/aura-cli/src/` -Expected: no output (exit 1 — zero hits). - -Run: `grep -rn 'Usage: aura' crates/aura-cli/src/ | wc -l` -Expected: `11` (the 10 edited sites + the untouched conforming -`run_args_from` literal at `main.rs:4012`). - -- [ ] **Step 17: Diff-shape gate** - -Run: `git diff --stat` -Expected: exactly 3 files changed — `crates/aura-cli/src/main.rs`, -`crates/aura-cli/src/graph_construct.rs`, -`crates/aura-cli/tests/cli_run.rs` (plus this plan/spec under `docs/` -if listed); no `fieldtests/` path, no other test file. - -- [ ] **Step 18: Smoke (worked example from the spec)** - -Run: `cargo run -q -p aura-cli -- sweep --strategy bogus; echo "exit=$?"` -Expected stderr line: -`aura: Usage: aura sweep [--strategy ] [--real [--from ] [--to ]] [--name | --trace ] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--channel ] [--window ] [--band-k ]` -Expected exit code line: `exit=2`. diff --git a/docs/specs/0101-normalize-cli-usage-casing.md b/docs/specs/0101-normalize-cli-usage-casing.md deleted file mode 100644 index 5d6138c..0000000 --- a/docs/specs/0101-normalize-cli-usage-casing.md +++ /dev/null @@ -1,210 +0,0 @@ -# Normalize CLI usage-message casing — Design Spec - -**Date:** 2026-07-02 -**Status:** Draft — awaiting sign-off (grounding-check gate; /boss auto-sign) -**Authors:** orchestrator + Claude - -## Goal - -Erase the three-way inconsistency in the aura CLI's hand-rolled usage -messages (issue #179). After the clap adoption (#175), the binary speaks -three styles at once: clap's own parse errors and one hand-rolled site say -`Usage:` (capital), six hand-rolled sites say `usage:` (lowercase), and -four hand-rolled closures carry no prefix word at all. This cycle -normalizes every hand-rolled usage line to the single house style clap -already speaks — **cosmetic only, no behaviour change**: exit codes, -emission channels (stderr), and control flow are byte-for-byte preserved; -only the usage-string literals and their casing-sensitive test pins move, -in lockstep. - -Decision log (house-style shape, bare-closure inclusion, refusal -exclusion, no de-dup refactor): issue #179, comment "Design -reconciliation (specify)". - -## Architecture - -### The house style (normative) - -One rule: **every hand-rolled usage line reads `Usage: aura …`** — -capital `Usage:` prefix and the program name included in the grammar, -exactly the shape of the two already-conforming producers: - -- clap itself (derive API, `#[command(name = "aura")]`) renders - `Usage: aura [OPTIONS]` on parse errors and `--help`; -- the one already-capital hand-rolled site, the built-in `run` branch - (`run_args_from`, `main.rs:4012`): `"Usage: aura run [--harness …] …"`. - -The emission convention around the literal is untouched: hand-rolled -sites keep printing through the existing `eprintln!("aura: {…}")` / -baked-in `aura: ` prefix, so the final stderr line reads -`aura: Usage: aura …` — which is already today's output shape of -the conforming `run_args_from` path. Exit codes keep the #175 partition -(usage = 2, runtime = 1) at every touched site. - -### Scope boundary - -**In scope (10 literal edits + 1 test-pin edit):** the 6 lowercase -`usage:` literals, the 4 bare usage closures, and the single -casing-sensitive test pin. - -**Out of scope (bytes preserved verbatim):** - -- The already-conforming site `run_args_from` (`main.rs:4012`) and all - clap-generated output. -- Every aura-specific refusal/diagnostic in the dispatch area — e.g. - `"no recorded geometry for symbol …"`, `"walkforward - requires >= 1 --axis to re-fit per window"`, the six `generalize` - refusals, `"cost flags require an R-evaluator harness …"`, - `"--harness is not valid with a blueprint file"`, `"--list-axes lists - axes and takes no other flags"`, `"run/mc requires a closed blueprint - …"`. A refusal is a diagnostic, not a usage line; clap itself keeps - the two apart (`error: …` vs the `Usage:` block). -- The duplicated run-blueprint usage literal (defined in `run_data_from` - at `main.rs:3991`, verbatim inline copy in `dispatch_run` at - `main.rs:4187`): both copies are normalized identically, but no shared - constant is extracted — a de-dup refactor exceeds the cosmetic - contract. -- Historical fieldtest corpus text quoting an old usage line - (`fieldtests/milestone-cost-model-graph/FINDINGS.md`) — the corpus is - a tracked record, never retro-edited. -- Rustdoc/comment prose saying "usage error" (no colon, not a message). - -## Concrete code shapes - -### Worked user-facing example (the acceptance evidence) - -Before (bare closure, built-in sweep): - -```console -$ aura sweep --strategy bogus -aura: sweep [--strategy ] [--real [--from ] [--to ]] [--name | --trace ] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--channel ] [--window ] [--band-k ] -$ echo $? -2 -``` - -After (house style; exit code unchanged): - -```console -$ aura sweep --strategy bogus -aura: Usage: aura sweep [--strategy ] [--real [--from ] [--to ]] [--name | --trace ] [--fast ] [--slow ] [--stop-length ] [--stop-k ] [--channel ] [--window ] [--band-k ] -$ echo $? -2 -``` - -And a lowercase site (mc, loaded-blueprint branch): - -```console -# before -aura: usage: mc --seeds [--name ] -# after -aura: Usage: aura mc --seeds [--name ] -``` - -### Normative literal edits (before → after, exact bytes) - -All in `crates/aura-cli` sources. Only the leading bytes of each literal -change; the grammar tails (`…` below) are preserved verbatim from the -current tree. - -| # | Site | Before (leading bytes) | After (leading bytes) | -|---|------|------------------------|-----------------------| -| 1 | `graph_construct.rs:191` (`introspect_cmd`) | `"aura: usage: aura graph introspect …"` | `"aura: Usage: aura graph introspect …"` | -| 2 | `main.rs:3991` (`run_data_from`) | `"usage: aura run …"` | `"Usage: aura run …"` | -| 3 | `main.rs:4187` (`dispatch_run`, inline copy of #2) | `"aura: usage: aura run …"` | `"aura: Usage: aura run …"` | -| 4 | `main.rs:4272` (`dispatch_runs`) | `"aura: usage: aura runs family [rank ]"` | `"aura: Usage: aura runs family [rank ]"` | -| 5 | `main.rs:4465` (`dispatch_mc`, blueprint) | `"usage: mc …"` | `"Usage: aura mc …"` | -| 6 | `main.rs:4503` (`dispatch_mc`, built-in) | `"usage: mc [--name \|--trace ] \| mc --strategy r-sma …"` | `"Usage: aura mc [--name \|--trace ] \| aura mc --strategy r-sma …"` | -| 7 | `main.rs:4288` (`dispatch_sweep`, blueprint) | `"sweep --axis …"` | `"Usage: aura sweep --axis …"` | -| 8 | `main.rs:4346` (`dispatch_sweep`, built-in) | `"sweep [--strategy …"` | `"Usage: aura sweep [--strategy …"` | -| 9 | `main.rs:4386` (`dispatch_walkforward`, blueprint) | `"walkforward --axis …"` | `"Usage: aura walkforward --axis …"` | -| 10 | `main.rs:4424` (`dispatch_walkforward`, built-in) | `"walkforward [--strategy …"` | `"Usage: aura walkforward [--strategy …"` | - -Site #6 carries two grammar alternatives separated by ` | `; **both** -gain the program name (`… | aura mc --strategy r-sma …`), so the line -stays internally consistent. - -### Test-pin edit (lockstep, exactly one casing-sensitive pin) - -`crates/aura-cli/tests/cli_run.rs:1409` (test `mc_rejects_real_flag`, pinning -site #6): - -```rust -// before -assert!(err.contains("usage"), …); -// after -assert!(err.contains("Usage"), …); -``` - -(The exact assertion text at that line is preserved except for the -pinned substring's casing; if the assertion carries a message argument, -it is left untouched.) - -All other pins are casing-neutral and stay byte-identical, verified -against the current suite: `cli_run.rs:116` and `:669` already require -capital `Usage` (satisfied by site `main.rs:4012` and by clap, -respectively — both unedited); `cli_run.rs:1444/1445` pin the verbs -`sweep`/`walkforward` and the flag `--real` (still substrings after the -prefix is prepended); `cli_run.rs:3192/3628/3876` pin out-of-scope -refusal texts (unedited); `tests/graph_construct.rs:294-297` pins only -the exit code and an echo of the bogus node name. - -## Components - -| File | Change | -|------|--------| -| `crates/aura-cli/src/main.rs` | 9 usage-literal edits (sites #2–#10) | -| `crates/aura-cli/src/graph_construct.rs` | 1 usage-literal edit (site #1) | -| `crates/aura-cli/tests/cli_run.rs` | 1 pin flip (`:1409`, lowercase `usage` → `Usage`) | - -No new files, no signature changes, no dependency changes. - -## Data flow - -Unchanged. Every touched literal keeps its current path to the user: -defined in its dispatch branch (as `&str`, `String` closure, or inline -`eprintln!`), printed to **stderr** with the `aura: ` program prefix, -followed by `exit(2)`. No emission moves between stdout/stderr, no exit -code changes, no message is added or removed — only bytes inside -existing literals change. - -## Error handling - -The #175 exit-code partition is the invariant to preserve: usage errors -exit 2, runtime failures exit 1. All twelve edited sites are on exit-2 -paths today and stay there. The suite's exit-code pins -(`exit_codes_partition_usage_two_from_runtime_one`, the per-command -rejection tests) run unmodified except for the single casing pin above. - -## Testing strategy - -No new tests: the change is cosmetic and the existing suite already pins -the touched surface. The gate is the suite itself: - -1. `cargo build --workspace` clean. -2. `cargo test --workspace` green with **exactly one** test-file edit - (the `cli_run.rs:1409` casing flip). Any other failing pin means an - edit strayed outside the normative table — fix the edit, not the pin. -3. `cargo clippy --workspace --all-targets -- -D warnings` clean. -4. Literal grep gates over `crates/aura-cli/src/`: - - `grep -rn '"usage:' crates/aura-cli/src/` → 0 hits; - - `grep -rn 'aura: usage:' crates/aura-cli/src/` → 0 hits; - - every hand-rolled usage literal now starts `Usage: aura ` (or - `aura: Usage: aura ` where the program prefix is baked into the - literal). -5. Smoke: `aura sweep --strategy bogus` prints the house-style line to - stderr and exits 2 (the worked example above). - -## Acceptance criteria - -- [ ] All 10 normative literal edits applied exactly as tabled (11 - grammar alternatives counting site #6's two; sites #2/#3 remain - verbatim twins). -- [ ] `cli_run.rs:1409` pins capital `Usage`; no other test bytes change. -- [ ] Grep gates (Testing strategy #4) pass: no lowercase `usage:` - literal survives in `crates/aura-cli/src/`. -- [ ] `cargo build` / `cargo test --workspace` / clippy `-D warnings` - all green. -- [ ] Exit codes unchanged at every touched site (usage = 2). -- [ ] Out-of-scope surfaces byte-identical: refusal diagnostics, - `run_args_from` literal, clap output, fieldtests corpus, README / - design-ledger prose.