audit(0099): cycle close — CLI clap adoption; ledger refreshed (C14); rm ephemeral spec/plan

Architect drift review (scope 780d823..HEAD, the sole gate — no regression
script) returned one medium ledger-gap, now resolved; otherwise drift-clean with
a positive What-holds:
- invariant 8 / C16 engine-domain separation preserved: clap is confined to
  crates/aura-cli/Cargo.toml; the whole diff touches only aura-cli/ + Cargo.lock
  + ephemeral docs; no engine/std/composites/analysis/registry/core/ingest crate
  mentions clap, so the frozen deploy artifact structurally cannot pick it up
  (aura-cli is a leaf binary). The 16 new lock entries are exactly clap's tree.
- C16 per-case admission honest: clap admitted with a documented rationale at the
  Cargo.toml site (replaces the hand-rolled parser + ten help surfaces; dev-loop
  tax, not frozen-artifact tax), the same admission form as sha2/libc.
- C14 automation-face served, execution layer intact: the usage=2/runtime=1
  partition, scoped --help, --version, and GNU flags match the spec; the domain
  fns keep their signatures (arg-plumbing via thin *_from adapters); new
  behaviour is pinned (partition property test, version, scoped-help, dual-grammar
  stray-positional guard).

Ledger refreshed: the C14 realization block now records the clap adoption + the
exit-code partition (usage=2/runtime=1) as a durable automation contract, before
the ephemeral spec that first stated it is removed (the drift item the architect
raised).

Deferred/forward: error-message casing normalization (#179, idea); the
machine-first help surface stays on the #157/C21 track (Fork B settled this cycle
as human/GNU convention compliance).

Verified green (orchestrator, this session): cargo build --workspace clean; cargo
clippy --workspace --all-targets -- -D warnings clean; cargo test --workspace
green. Cycle drift-clean.

closes #175
This commit is contained in:
2026-07-01 20:11:11 +02:00
parent fa42bf3878
commit 27f0f8ea11
4 changed files with 20 additions and 1265 deletions
+20
View File
@@ -1068,6 +1068,26 @@ runnable substrate but is core to aura's identity, not optional. The pivot keeps
this contract's core intact — and arguably tightens it: a browser reading a
serialized trace file is a stricter "no UI knowledge in the engine" than egui
reaching zero-copy into the live SoA columns.
**Realization (cycles 0098/0099, #175 — the CLI meets GNU/clig.dev conventions
via clap).** The programmatic/CLI face's argument surface moved from a hand-rolled
argv parser to a `clap` derive parser (admitted under the C16 per-case dependency
policy — research-side, a dev-loop/compile tax, never a frozen-artifact tax;
invariant 8 untouched, the change is confined to `aura-cli`, a leaf binary the
frozen deploy artifact cannot pick up). One declarative source now yields scoped
`aura <sub> --help`, `--version`/`-V`, a per-flag Options section, and GNU
`--flag=value` / `--` / long-option abbreviation. The **exit-code partition** is a
durable part of the automation contract, so a caller can branch on the failure
class without parsing stderr: **exit 0 = success**; **exit 2 = usage error** — a
command-line fault (clap parse errors + aura's post-parse argument-structure
validations, *including* the content of an argv-named blueprint file, which is
itself an argument); **exit 1 = runtime failure** — a well-formed command whose
needed environment / recorded state is missing, or bad piped stdin data. The four
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
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).
### C15 — Resampling-as-node; sessions/calendars
**Guarantee.** A resampler is a node (finer stream → coarser bar stream),