Motivation
blazerules accepts a --config run.yaml that maps onto its flags, with a stated rule: explicit flags override the file. The value isn't the config file (aeb deliberately doesn't parse external config — .ae is the source of truth) — it's the precedence discipline: there is one documented, tested winner when the same setting is expressible in more than one place.
aeb has several settings expressible in multiple layers today — AEB_JOBS (env) vs a future flag, --sandbox/--vet (flag) vs any .ae-declared intent, AEB_COVERAGE (env, set by the trampoline) vs --coverage (flag). The override order works in practice but is not stated in one place, so a contributor can't reason about it and a user can't predict it.
Proposal
Document (and where thin, enforce) a single precedence order for aeb settings. Proposed order, strongest-wins:
- Explicit CLI flag (
--jobs, --coverage, --sandbox, --report) — always wins.
- Environment variable (
AEB_JOBS, AEB_COVERAGE, DOCKER_HOST) — wins over defaults.
.ae-declared intent (setters in the dot-file) — the build's own declaration.- Built-in default (
nproc for jobs, non-coverage, no sandbox).
- Add a short Configuration precedence section to
README.md stating the order once.
- Where a setting is currently env-only (e.g.
AEB_JOBS), add the corresponding flag (--jobs N) so the layering is real, and wire flag-beats-env in the trampoline arg parse.
- This is aligned with the load-bearing
.ae-is-truth principle — no new config-file parser. It only clarifies how the existing flag/env/.ae/default layers rank.
Acceptance criteria
Not being asked
NOT asking aeb to read a run.yaml/TOML/JSON config file. This is precedence documentation + closing the one env-only gap (jobs), nothing more.
Motivation
blazerules accepts a
--config run.yamlthat maps onto its flags, with a stated rule: explicit flags override the file. The value isn't the config file (aeb deliberately doesn't parse external config —.aeis the source of truth) — it's the precedence discipline: there is one documented, tested winner when the same setting is expressible in more than one place.aeb has several settings expressible in multiple layers today —
AEB_JOBS(env) vs a future flag,--sandbox/--vet(flag) vs any.ae-declared intent,AEB_COVERAGE(env, set by the trampoline) vs--coverage(flag). The override order works in practice but is not stated in one place, so a contributor can't reason about it and a user can't predict it.Proposal
Document (and where thin, enforce) a single precedence order for aeb settings. Proposed order, strongest-wins:
--jobs,--coverage,--sandbox,--report) — always wins.AEB_JOBS,AEB_COVERAGE,DOCKER_HOST) — wins over defaults..ae-declared intent (setters in the dot-file) — the build's own declaration.nprocfor jobs, non-coverage, no sandbox).README.mdstating the order once.AEB_JOBS), add the corresponding flag (--jobs N) so the layering is real, and wire flag-beats-env in the trampoline arg parse..ae-is-truth principle — no new config-file parser. It only clarifies how the existing flag/env/.ae/default layers rank.Acceptance criteria
README.mdhas a Configuration precedence section listing the 4-tier order.--jobs Nexists and beatsAEB_JOBS;AEB_JOBSstill beats thenprocdefault.--coverageandAEB_COVERAGEprecedence is documented and consistent.jobs.Not being asked
NOT asking aeb to read a
run.yaml/TOML/JSON config file. This is precedence documentation + closing the one env-only gap (jobs), nothing more.