Brummel/Aura
1
0
Fork 0
Code Issues 31 Pull Requests Actions Packages Projects Releases Wiki Activity

Normalize CLI error-message casing (Usage:/usage:/bare) after clap adoption #179

New Issue
Closed
opened 2026-07-01 20:06:34 +02:00 by Brummel · 3 comments
Brummel commented 2026-07-01 20:06:34 +02:00
Owner
Copy Link
Copy Source

Context

After the clap adoption (#175, cycles 0098/0099), the aura CLI's error-message
casing is mixed:

  • Usage: (capital) — emitted by clap itself on parse errors, and by the
    built-in run branch (run_args_from).
  • usage: (lowercase) — preserved aura messages in several dispatch
    handlers (run_data_from, dispatch_run blueprint-branch, dispatch_runs,
    dispatch_mc) and graph introspect.
  • bare (no usage prefix) — the sweep/walkforward usage closures and every
    aura-specific refusal (R-evaluator harness, requires >= 1 --axis,
    no recorded geometry, etc.).

Task

Normalize the casing to a single house style (recommend clap's capitalized
Usage: for consistency with the parser it now wraps).

Constraints

Cosmetic only — no behaviour change. Several .contains() test pins constrain
the strings: the capital/lowercase Usage/usage word-boundary is pinned at
cli_run.rs (run_with_trailing_token, no_args -> capital; mc_rejects_real_flag
-> lowercase), and the aura-specific message substrings are pinned throughout.
A normalization pass must update those pins in lockstep.

Deferred deliberately from #175 iterations 1-2: high pin-churn, zero functional
gain. Low priority; strike if not worth the churn.

## Context After the clap adoption (#175, cycles 0098/0099), the aura CLI's error-message casing is mixed: - **`Usage:`** (capital) — emitted by clap itself on parse errors, and by the built-in `run` branch (`run_args_from`). - **`usage:`** (lowercase) — preserved aura messages in several dispatch handlers (`run_data_from`, `dispatch_run` blueprint-branch, `dispatch_runs`, `dispatch_mc`) and `graph introspect`. - **bare** (no `usage` prefix) — the sweep/walkforward usage closures and every aura-specific refusal (`R-evaluator harness`, `requires >= 1 --axis`, `no recorded geometry`, etc.). ## Task Normalize the casing to a single house style (recommend clap's capitalized `Usage:` for consistency with the parser it now wraps). ## Constraints Cosmetic only — no behaviour change. Several `.contains()` test pins constrain the strings: the capital/lowercase `Usage`/`usage` word-boundary is pinned at `cli_run.rs` (run_with_trailing_token, no_args -> capital; mc_rejects_real_flag -> lowercase), and the aura-specific message substrings are pinned throughout. A normalization pass must update those pins in lockstep. Deferred deliberately from #175 iterations 1-2: high pin-churn, zero functional gain. Low priority; strike if not worth the churn.
Brummel added the idea label 2026-07-01 20:06:34 +02:00
Brummel commented 2026-07-02 12:26:45 +02:00
Author
Owner
Copy Link
Copy Source

Design reconciliation (specify)

Spec: 0101-normalize-cli-usage-casing. This issue's body names the target style but leaves four scope forks open; this comment records their resolution.

  • Fork: house-style shape → every hand-rolled usage line normalizes to Usage: aura <verb> ... (capital prefix, program name included), keeping the existing aura: stderr convention — final stderr shape aura: Usage: aura <verb> ....
    Basis: derived — the issue names clap as the yardstick ("recommend clap's capitalized Usage: for consistency with the parser it now wraps") and cites the built-in run branch (run_args_from) as the already-conforming site; both clap's own output and that exemplar include the program name (Usage: aura run ...), so the verb-only lines (sweep ..., mc ...) normalize to the exemplar's shape rather than surviving as a second style.

  • Fork: bare usage closures → included. The four prefix-less usage closures (sweep/walkforward, blueprint and built-in branches each) gain the same Usage: aura prefix.
    Basis: derived — the issue's own inventory lists "bare (no usage prefix)" as one of the three inconsistent states the task normalizes; leaving them bare would keep two styles alive.

  • Fork: non-usage refusal texts → untouched. Aura-specific diagnostics (e.g. "no recorded geometry ...", "requires >= 1 --axis ...", the generalize refusals, the cost-flag refusal) keep their current bytes.
    Basis: derived — a refusal is a diagnostic, not a usage line; the house style's own reference (clap) separates the diagnostic (error: ...) from the grammar block (Usage: ...), so prefixing a refusal with Usage: would mislabel it, and the issue's task sentence names only the usage-prefix casing as the normalization target.

  • Fork: duplicated run-blueprint usage literal (the run_data_from literal and its verbatim inline copy in dispatch_run) → both copies normalized identically; no de-duplication refactor.
    Basis: derived — the cycle's contract is "Cosmetic only — no behaviour change"; extracting a shared constant is a code refactor outside that contract.

Test pins move in lockstep, as this issue's Constraints section mandates: exactly one pin is casing-sensitive to this change (the mc built-in usage assertion pinning lowercase usage) and flips to the capital; the remaining pins assert verbs/flags/exit codes and are casing-neutral (verified against the test suite's assertions).

Design settled — ready for spec production.

## Design reconciliation (specify) Spec: 0101-normalize-cli-usage-casing. This issue's body names the target style but leaves four scope forks open; this comment records their resolution. - **Fork: house-style shape** → every hand-rolled usage line normalizes to `Usage: aura <verb> ...` (capital prefix, program name included), keeping the existing `aura: ` stderr convention — final stderr shape `aura: Usage: aura <verb> ...`. Basis: derived — the issue names clap as the yardstick ("recommend clap's capitalized Usage: for consistency with the parser it now wraps") and cites the built-in run branch (`run_args_from`) as the already-conforming site; both clap's own output and that exemplar include the program name (`Usage: aura run ...`), so the verb-only lines (`sweep ...`, `mc ...`) normalize to the exemplar's shape rather than surviving as a second style. - **Fork: bare usage closures** → included. The four prefix-less usage closures (sweep/walkforward, blueprint and built-in branches each) gain the same `Usage: aura ` prefix. Basis: derived — the issue's own inventory lists "bare (no usage prefix)" as one of the three inconsistent states the task normalizes; leaving them bare would keep two styles alive. - **Fork: non-usage refusal texts** → untouched. Aura-specific diagnostics (e.g. "no recorded geometry ...", "requires >= 1 --axis ...", the generalize refusals, the cost-flag refusal) keep their current bytes. Basis: derived — a refusal is a diagnostic, not a usage line; the house style's own reference (clap) separates the diagnostic (`error: ...`) from the grammar block (`Usage: ...`), so prefixing a refusal with `Usage:` would mislabel it, and the issue's task sentence names only the usage-prefix casing as the normalization target. - **Fork: duplicated run-blueprint usage literal** (the `run_data_from` literal and its verbatim inline copy in `dispatch_run`) → both copies normalized identically; no de-duplication refactor. Basis: derived — the cycle's contract is "Cosmetic only — no behaviour change"; extracting a shared constant is a code refactor outside that contract. Test pins move in lockstep, as this issue's Constraints section mandates: exactly one pin is casing-sensitive to this change (the mc built-in usage assertion pinning lowercase `usage`) and flips to the capital; the remaining pins assert verbs/flags/exit codes and are casing-neutral (verified against the test suite's assertions). Design settled — ready for spec production.
Brummel commented 2026-07-02 12:32:08 +02:00
Author
Owner
Copy Link
Copy Source

Autonomous spec sign-off (grounding-check PASS)

Spec 0101-normalize-cli-usage-casing was signed autonomously; no human signed. The signature is the independent grounding-check reviewer's PASS: every load-bearing assumption about current behaviour is ratified by a currently-green test — the mc built-in usage assertion as the sole lowercase-casing pin, the two capital-Usage pins and their out-of-scope producers (the built-in run branch and clap itself), the verb/flag pins that survive the prefix insertion, the graph-introspect exit-code-only pin, and the usage=2/runtime=1 exit-code partition. All ten "before" literals were byte-verified at their cited sites.

The scope decisions in force (house-style shape Usage: aura <verb> ..., inclusion of the four bare closures, exclusion of refusal diagnostics, no de-dup refactor of the duplicated run-blueprint literal) are recorded in the comment titled "Design reconciliation (specify)" on this issue.

Spec signed — ready for implementation planning.

## Autonomous spec sign-off (grounding-check PASS) Spec 0101-normalize-cli-usage-casing was signed autonomously; no human signed. The signature is the independent grounding-check reviewer's PASS: every load-bearing assumption about current behaviour is ratified by a currently-green test — the mc built-in usage assertion as the sole lowercase-casing pin, the two capital-`Usage` pins and their out-of-scope producers (the built-in run branch and clap itself), the verb/flag pins that survive the prefix insertion, the graph-introspect exit-code-only pin, and the usage=2/runtime=1 exit-code partition. All ten "before" literals were byte-verified at their cited sites. The scope decisions in force (house-style shape `Usage: aura <verb> ...`, inclusion of the four bare closures, exclusion of refusal diagnostics, no de-dup refactor of the duplicated run-blueprint literal) are recorded in the comment titled "Design reconciliation (specify)" on this issue. Spec signed — ready for implementation planning.
Brummel commented 2026-07-02 12:56:10 +02:00
Author
Owner
Copy Link
Copy Source

Implementation-phase decision (spec deviation, recorded)

The landed change matches the spec 0101-normalize-cli-usage-casing normative table byte-for-byte (10 literal edits, 1 pin flip). One deviation from the spec's acceptance wording is kept deliberately:

  • Fork: three additive house-style regression tests vs. the acceptance line "no other test bytes change" → kept.
    The end-to-end coverage phase added three tests to the CLI integration suite: (1) the built-in sweep/walkforward usage lines must lead with aura: Usage: aura <verb> , (2) the built-in mc usage must name the program in BOTH |-separated grammar alternatives, (3) the blueprint-branch mc usage must read aura: Usage: aura mc <blueprint.json>.
    Basis: derived — the spec's premise "the existing suite already pins the touched surface" turned out to overstate: the pre-existing pins check only the verb token / a single Usage occurrence, so a regression re-barening the closures or dropping the second mc alternative's program name would have passed them (each new test's doc-comment names the exact gap). The acceptance line's intent — no silent rewrites of existing assertions — is honored: no pre-existing assertion byte changed beyond the one mandated lockstep pin flip; the three tests are purely additive.

Verification at landing: full workspace suite green (rc=0; the CLI integration target now 133 tests), clippy -D warnings clean, literal grep gates exact (zero lowercase usage: literals; 11 Usage: aura source lines = 10 edited + 1 pre-conforming), smoke run prints the house-style line and exits 2.

## Implementation-phase decision (spec deviation, recorded) The landed change matches the spec 0101-normalize-cli-usage-casing normative table byte-for-byte (10 literal edits, 1 pin flip). One deviation from the spec's acceptance wording is kept deliberately: - **Fork: three additive house-style regression tests vs. the acceptance line "no other test bytes change"** → kept. The end-to-end coverage phase added three tests to the CLI integration suite: (1) the built-in sweep/walkforward usage lines must lead with `aura: Usage: aura <verb> `, (2) the built-in mc usage must name the program in BOTH `|`-separated grammar alternatives, (3) the blueprint-branch mc usage must read `aura: Usage: aura mc <blueprint.json>`. Basis: derived — the spec's premise "the existing suite already pins the touched surface" turned out to overstate: the pre-existing pins check only the verb token / a single `Usage` occurrence, so a regression re-barening the closures or dropping the second mc alternative's program name would have passed them (each new test's doc-comment names the exact gap). The acceptance line's intent — no silent rewrites of existing assertions — is honored: no pre-existing assertion byte changed beyond the one mandated lockstep pin flip; the three tests are purely additive. Verification at landing: full workspace suite green (rc=0; the CLI integration target now 133 tests), clippy -D warnings clean, literal grep gates exact (zero lowercase `usage:` literals; 11 `Usage: aura` source lines = 10 edited + 1 pre-conforming), smoke run prints the house-style line and exits 2.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
BLOCKER
Core functionality blocked; preempts other selection
 bug
Observable misbehaviour
 feature
Substantial extension; no full spec required
 idea
Droppable; no commitment
No Label idea
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claude (Claude) Brummel
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Brummel/Aura#179
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?