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

Cost-flag CLI ergonomics: units hint, negative-rate diagnostic, non-R-harness handling (+ C10 spec_gap) #153

New Issue
Closed
opened 2026-06-29 02:33:50 +02:00 by Brummel · 1 comment
Brummel commented 2026-06-29 02:33:50 +02:00
Owner
Copy Link
Copy Source

Surfaced by the milestone-close fieldtest of #148 ("Cost-model graph (in R)") — all non-blocking (the capability is delivered end-to-end); these are CLI ergonomics / diagnostic polish on the cost-flag surface. Bundled as one issue rather than four micro-issues.

1. Cost-flag units / scale are undiscoverable at the point of use

The aura run usage string offers only [--cost-per-trade <f64>] [--slip-vol-mult <f64>] [--carry-per-cycle <f64>] — no unit, no per-close-vs-per-held-cycle note, no scale guidance. A user must trial magnitudes (0.0001 / 0.001 / 0.01) to find one that moves net-R sensibly, because the R-normalizer (cost-in-R = cost / |entry − stop|, the stop distance) and --carry-per-cycle's unit (price units, per engine cycle — not per day, not an overnight swap) are nowhere at the CLI. The semantics are in ledger C10 + the glossary, just not at the point of use. Proposed: a per-flag units note, e.g. "price units, charged in R as cost/|entry−stop|; --carry-per-cycle is per engine cycle".

2. Negative cost-rate guard prints the bare usage string, names no cause

--carry-per-cycle -0.001 (and --cost-per-trade -0.5) correctly exit 2 (the guard is capability-safe), but the diagnostic is the entire 1-line usage dump — it never says why (e.g. "cost rate must be ≥ 0"), and the usage string never states the non-negativity constraint, so a sign typo is indistinguishable from a mistyped flag name. Proposed: emit cost rate must be non-negative, got <v>.

3. Cost flags silently no-op on a non-R harness (sma / macd) + an undefined-corner spec_gap

aura run --harness sma --cost-per-trade 0.001 exits 0 with output byte-identical to the no-cost sma run — no r block, no net_*, no warning. A user who believes they measured a cost-adjusted result got an unmodified one with no signal the flag did nothing. Spec_gap: C10 / the glossary define cost only against the R chain (gross R → net R) and never constrain what a cost flag should do on a harness that produces no R at all; the project currently picked "silently accept and ignore", but "reject: cost requires an R-evaluator harness" was equally plausible. Decide error-vs-warn and add a one-line C10 note pinning it; either way give the user feedback (the missing-feedback foot-gun stands regardless of which behaviour is chosen).

Context

Milestone #148 closed green on the fieldtest (commit range fc52b4f..the milestone-close commit; fieldtest evidence under fieldtests/milestone-cost-model-graph/). These four items were classified friction×3 + spec_gap×1; none gates the close. The separate doc-rot finding (docs/project-layout.md describes the retired aura backtest --broker pepperstone path) is folded into #151.

Surfaced by the milestone-close fieldtest of #148 ("Cost-model graph (in R)") — all non-blocking (the capability is delivered end-to-end); these are CLI ergonomics / diagnostic polish on the cost-flag surface. Bundled as one issue rather than four micro-issues. ## 1. Cost-flag units / scale are undiscoverable at the point of use The `aura run` usage string offers only `[--cost-per-trade <f64>] [--slip-vol-mult <f64>] [--carry-per-cycle <f64>]` — no unit, no per-close-vs-per-held-cycle note, no scale guidance. A user must trial magnitudes (`0.0001 / 0.001 / 0.01`) to find one that moves net-R sensibly, because the R-normalizer (`cost-in-R = cost / |entry − stop|`, the stop distance) and `--carry-per-cycle`'s unit (price units, **per engine cycle** — not per day, not an overnight swap) are nowhere at the CLI. The semantics *are* in ledger C10 + the glossary, just not at the point of use. Proposed: a per-flag units note, e.g. "price units, charged in R as cost/|entry−stop|; --carry-per-cycle is per engine cycle". ## 2. Negative cost-rate guard prints the bare usage string, names no cause `--carry-per-cycle -0.001` (and `--cost-per-trade -0.5`) correctly exit 2 (the guard is capability-safe), but the diagnostic is the entire 1-line usage dump — it never says *why* (e.g. "cost rate must be ≥ 0"), and the usage string never states the non-negativity constraint, so a sign typo is indistinguishable from a mistyped flag name. Proposed: emit `cost rate must be non-negative, got <v>`. ## 3. Cost flags silently no-op on a non-R harness (sma / macd) + an undefined-corner spec_gap `aura run --harness sma --cost-per-trade 0.001` exits 0 with output byte-identical to the no-cost `sma` run — no `r` block, no `net_*`, no warning. A user who believes they measured a cost-adjusted result got an unmodified one with no signal the flag did nothing. **Spec_gap:** C10 / the glossary define cost only against the R chain (gross R → net R) and never constrain what a cost flag should do on a harness that produces no R at all; the project currently picked "silently accept and ignore", but "reject: cost requires an R-evaluator harness" was equally plausible. Decide error-vs-warn and add a one-line C10 note pinning it; either way give the user feedback (the missing-feedback foot-gun stands regardless of which behaviour is chosen). ## Context Milestone #148 closed green on the fieldtest (commit range fc52b4f..the milestone-close commit; fieldtest evidence under `fieldtests/milestone-cost-model-graph/`). These four items were classified friction×3 + spec_gap×1; none gates the close. The separate doc-rot finding (`docs/project-layout.md` describes the retired `aura backtest --broker pepperstone` path) is folded into #151.
Brummel added the idea label 2026-06-29 02:33:50 +02:00
Brummel commented 2026-06-29 11:16:17 +02:00
Author
Owner
Copy Link
Copy Source

/boss decision log (autonomous run, project aura, 2026-06-29).

Item 3 fork — cost flags on a non-R harness: error vs. warn.

The issue notes both readings were plausible and the project currently picked "silently accept and ignore". Deriving the answer from the project's settled discipline rather than bouncing:

  • Chosen: reject, exit 2 with a named diagnostic, e.g. cost flags require an R-evaluator harness (stage1-r); --harness sma/macd produces no R to charge against.
  • Rationale (derivable, not preference): aura's pervasive stance is refuse-don't-guess / fail-loud — C10 refuse-don't-guess (exit 2 on absent geometry), the #107 "every error path exits 2, never panics" rule, and the negative-rate guard in this very issue already exits 2. A silent no-op is the one behaviour the issue itself calls a "foot-gun". Rejecting is the only option consistent with every sibling guard; warn-and-continue would be the lone silent-ish exception in a fail-loud surface.
  • C10 note: add a one-line ledger note pinning "cost flags are defined only against an R-evaluator harness; on a non-R harness they are a usage error (exit 2)", closing the named spec_gap.

Items 1 (per-flag units hint in the usage string) and 2 (negative-rate diagnostic cost rate must be non-negative, got <v> + state the constraint in usage) carry no fork — implemented as specified.

Routing: settled design + a C10 amendment → specify (bounded, grounding-checked, boss-signed) → planner → implement.

> `/boss` decision log (autonomous run, project aura, 2026-06-29). **Item 3 fork — cost flags on a non-R harness: error vs. warn.** The issue notes both readings were plausible and the project currently picked "silently accept and ignore". Deriving the answer from the project's settled discipline rather than bouncing: - **Chosen: reject, exit 2** with a named diagnostic, e.g. `cost flags require an R-evaluator harness (stage1-r); --harness sma/macd produces no R to charge against`. - **Rationale (derivable, not preference):** aura's pervasive stance is *refuse-don't-guess / fail-loud* — C10 refuse-don't-guess (exit 2 on absent geometry), the #107 "every error path exits 2, never panics" rule, and the **negative-rate guard in this very issue already exits 2**. A silent no-op is the one behaviour the issue itself calls a "foot-gun". Rejecting is the only option consistent with every sibling guard; warn-and-continue would be the lone silent-ish exception in a fail-loud surface. - **C10 note:** add a one-line ledger note pinning "cost flags are defined only against an R-evaluator harness; on a non-R harness they are a usage error (exit 2)", closing the named spec_gap. Items 1 (per-flag units hint in the usage string) and 2 (negative-rate diagnostic `cost rate must be non-negative, got <v>` + state the constraint in usage) carry no fork — implemented as specified. Routing: settled design + a C10 amendment → `specify` (bounded, grounding-checked, boss-signed) → planner → implement.
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#153
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?