Rename the vestigial stage1-* identifier family to a sequence-free name
#174
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Brummel/Aura#174
Reference in New Issue
Block a user
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?
Problem
The
stage1-*identifier family carries an ordinal that no longer denotesanything. The two-stage research model — Stage 1 (flat-1R feed-forward R
research) gated ahead of Stage 2 (currency P&L / fixed-fractional sizing /
realistic broker, entered only after
E[R] > 0) — was dropped in the C10reframe (
29cdc8c; ledgerdocs/design/INDEX.md:672-904; glossarydocs/glossary.md:250-252). Research is now one pure feed-forward R loop(gross R → net R via the cost model); there is no Stage 2. The glossary already
records the residue:
Why this is a defect, not a harmless relic
A
1structurally implies a2. A reader without the design ledger in viewmeets
--strategy stage1-rorStrategy::Stage1Rand cannot tell what the1means or where
2is — the name provokes exactly the wrong question. Theglossary explanation lives at a location the reader is not looking at while
reading
crates/aura-cli/src/main.rs; it helps only a reader who already knowsto look it up.
Why rename rather than annotate
The clarifying note cannot be placed "where the reader stumbles": there are five
definition sites and hundreds of usages, 72 of them the bare string literal
"stage1-r"/"stage1-breakout"/"stage1-meanrev"(CLI parsing, tests),which has no definition to jump to. Per-site comments would not scale and would
themselves be a drift source (multiple diverging copies). The only annotation
that travels with every occurrence is the name itself — hence a rename.
Scope / affected sites
Verified counts: 497
stage1occurrences acrosscrates/(excl.target/),205 of them in
crates/aura-cli/tests/cli_run.rs; 72 bare selector-stringliterals; three selector strings (
stage1-r,stage1-breakout,stage1-meanrev).Strategy::Stage1R/Stage1Breakout/Stage1MeanRevand their parse arms (crates/aura-cli/src/main.rs:1631,:1685,:1808,:2314).stage1_r_graph(main.rs:2858),stage1_breakout_graph,stage1_meanrev_graph; runnerrun_stage1_r(main.rs:3467); gridStage1RGrid(main.rs:1144); nestedstage1_signalcomposite.stage1_r_friendly_name(
main.rs:1192) — the C18 registry-record identity, so a rename toucheson-disk record names, not only source symbols.
crates/aura-cli/tests/cli_run.rs(e.g.stage1_r_single_run_output_golden,:2074) assert the literalstage1-rin output — they move with the rename.
crates/aura-engine/tests/stage1_r_e2e.rs,stage1_meanrev_e2e.rs.crates/aura-std/src/sizer.rs:5-8reuses the dead ordinal and should be reworded in the same pass.
The golden-test churn and the family-record-name change are implementation
effort, not a reason to keep a misleading name (design rationale ≠
implementation effort, per
CLAUDE.md).Open sub-decision
The replacement token — a sequence-free, self-describing name for the shipped
feed-forward R harness family. Candidates:
feedforward-r,ffr,r-harness.Not yet settled.
Acceptance
stage1/stage2ordinal survives in a live identifier oruser-facing string (the glossary's historical note may remain as history)
*_friendly_name, and thegolden tests renamed consistently
crates/aura-std/src/sizer.rs"Stage-2 seam" note reworded to drop thedead ordinal
cargo build --workspaceandcargo test --workspacegreenDesign reconciliation (specify)
Spec: 0100-rename-stage1-family-to-r-family. The forks below are listed open (or unstated) in the issue body; this records their resolution.
Fork: replacement token (the issue's open sub-decision) → the r-family: selectors
r-sma,r-breakout,r-meanrev; identifiersStrategy::RSma/RBreakout/RMeanRev,HarnessKind::RSma,r_sma_*/r_breakout_*/r_meanrev_*, shared scaffoldingwrap_stage1r→wrap_r,run_signal_stage1r→run_signal_r,Stage1RGrid→RGrid,STAGE1_R_*→R_SMA_*, compositestage1_signal→sma_signal.Basis: derived: the R yardstick is the family's live discriminator against the pip-legacy selectors (the CLI itself refuses
--harness sma/macdwith "produces no R"), and naming every member by its signal under ther-marker makes the set uniform with its signal-named siblings (sma,macd,momentum) and with the existing R token ecology (r_equity,RMetrics,mean_r).Rejected candidates:
ffr— an opaque acronym recreates the exact must-look-it-up defect the rename removes.r-harness— "harness" is tier vocabulary every selector satisfies, so it discriminates nothing and does not compose across members.feedforward-*— post-C10 every shipped strategy is feed-forward, so the marker is as vacuous a discriminator asstage1, and it leaves member 1 yardstick-named while its siblings are signal-named. A prefix-only swap is additionally impossible for member 1 (<prefix>-rdegenerates), which is why the member names move to uniform signal-naming.Fork: fieldtests/ corpus (10+10+14 hits in committed scripts/findings) → untouched.
Basis: derived: committed fieldtest dirs are the historical evidence of past cycles; rewriting them falsifies the record — the same class as ledger history, which the issue explicitly lets stand.
Fork: dead-ordinal doc prose beyond the issue-listed sizer.rs note (aura-analysis, aura-composites, position_management rustdoc, risk_executor test prose, project CLAUDE.md invariant 7, ledger live CLI-surface lines, glossary residue-entry tail, Cargo.toml comments) → reworded to the post-C10 vocabulary (feed-forward research loop / live-deploy edge); ledger HISTORY sections and the glossary's historical "Stage 1 / Stage 2" entry itself stay, with only its "survives as identifier name" clause updated to record the rename.
Basis: derived: rustdoc and normative project prose are user-facing surfaces, and acceptance box 1 forbids a surviving ordinal outside history; the rewording records the already-ratified C10 reframe (ledger
29cdc8c), it decides nothing new.Fork: persisted identity / migration → the two
stage1_signalfixture JSONs are regenerated via their#[ignore]regenerator tests and renamed with the composite;unknown_node.jsonis hand-edited; no migration of userruns/artifacts; the content-id/topology-hash shift from renaming the composite is accepted.Basis: derived: no test pins a literal hash and the registry never parses record names (verified by recon), so the shift is test-invisible;
runs/artifacts are runtime data outside the repo contract.Correction to the issue body:
stage1_r_friendly_namemaps param names away from stage1 and writes no on-disk bytes — the only persisted stage1 token is thestage1_signalcomposite name (the param-space prefix, serialized in three test fixtures and feedingtopology_hash/content-id). The "rename touches on-disk record names" clause in the body holds only for that composite name, not for the friendly-name function.Out of scope (false positive):
crates/aura-engine/src/harness.rs:1898— "stage1/stage2/stage3" there are resampling stages of a reduction test, unrelated to this family.Implementation-phase fork decisions (implement, cycle 0100)
Three decisions taken while resolving the quality gate's findings on the prose task; recorded here per the run's decision-log discipline.
Fork: ledger pointer edits inside the C10 section (INDEX.md :617, :740) → the renames stand (
stage1-r→r-sma,stage1_r_graph→r_sma_graph).Basis: derived: both lines are present-tense contract text describing the current wiring (the legacy pip-yardstick clause naming the shipped harness; the run-path cost-flag pointer), and a ledger pointer to current code must track the code or the contract points at a symbol that no longer exists. The "history sections stay" survivor clause binds the dated reframe narrative (what Stage-1/Stage-2 meant), not current-code pointers that happen to sit inside the C10 section. This refines the third fork of the "Design reconciliation (specify)" comment (2026-07-02, on this issue), which framed the survivors as line ranges: live-vs-history is a property of the text, not of a line range.
Fork: CLAUDE.md invariant 7 — token-swap vs faithful rewrite → faithful rewrite.
Basis: derived: the minimal token-swap the plan prescribed removed the "Stage 2" marker but left the marked retired design (gated currency layer entered after E[R] > 0, realistic brokers, Sizer/z⁻¹/flat-1R-vs-compounding as research mechanisms, the event table "feeding realistic brokers") standing as unmarked live prose — contradicting the ledger, which retires that paragraph in full (INDEX.md C10 reframe, "retired in full" list). The invariant now records the post-C10 reality: pure feed-forward research loop (flat-1R, gross→net R via the cost-model graph, no Sizer, no equity feedback, no z⁻¹), money/fixed-fractional/compounding as post-hoc money-management transforms at the deploy/account layer, the live broker as an I/O adapter at the recording/deploy edge, the position-event table as the deploy/reconciliation audit artifact. This records the already-ratified C10 reframe (ledger
29cdc8c); it decides nothing new.Fork: the "Account mode (netting/hedging) is a composition constraint" clause in invariant 7 → dropped.
Basis: derived: the clause is backed nowhere in the design ledger or glossary (zero grep hits for netting/hedging/account-mode), and its pre-reframe anchor — the in-graph Broker/Account composite — was retired by the C10 reframe; an unbacked clause has no place in the binding invariants list, and if account modes return with the live-edge work they will enter through the ledger first.
Correction to the spec's plan (observation, no decision): the implement loop's exhaustiveness probes found and fixed four prose sites the plan's case-sensitive substitution lists missed (a space-form "stage1 signal" expectation string, a "Stage-1-R stream" line, and three capitalized "Stage-1" doc lines in the renamed r_sma e2e test); all were reworded within the spec's dead-ordinal intent and pass the acceptance grep gate.