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

Explain the two-layer architecture in the CLI help — research verbs as sugar over process/campaign documents #315

New Issue
Closed
opened 2026-07-23 12:16:08 +02:00 by claude · 2 comments
claude commented 2026-07-23 12:16:08 +02:00
Collaborator
Copy Link
Copy Source

aura --help is a flat list of 16 verbs. process ("methodology") and campaign ("experiment intent") sit unexplained beside the research verbs; nothing states that run/sweep/walkforward/mc/generalize are sugar over the same registered document kinds, that the data plane is directly authorable, what the bias-as-target-position execution semantics are, or how a persisted trace comes to exist. For a reader without access to this repository — the exact situation of a downstream agent — the help is the only always-present self-description the binary has, and today it describes nothing but the verb inventory.

Field evidence (2026-07-22 external field test, triaged in #314): the agent drove the whole day through the sugar verbs and reached the data plane only as an escape hatch after forensics — in one workspace, two failed signal-side workaround blueprints (file mtimes 12:59-13:05) precede the first hand-authored data-plane documents (13:06 a minimal process document, 13:16 a campaign overriding the risk block to disable the protective stop), whose schemas were reverse-engineered by introspecting the CAS artifacts under runs/, not learned from the help. Once discovered, the layer carried real work — aura campaign validate/register/run/introspect were invoked 27/20/16/13 times across the day's sessions — so the gap is discoverability, not capability.

Direction:

  • The top-level help opens with a short concepts paragraph: the two layers (research verbs as sugar writing registered process/campaign documents; the data plane directly authorable via aura process / aura campaign), one sentence on the bias-as-target-position + protective-stop execution model, and one on how traces are produced and consumed (sweep --real --trace / walkforward --real --trace -> chart / measure).
  • Each sugar verb's long help names the document kind it desugars to.
  • The error messages already model the target register (the --trace refusals name #224 and point to the verbs that work); the help text would meet that same bar.

The generated agent bootstrap card (#267) remains the richer onboarding artifact; the help is the zero-setup surface that exists even when no card was generated. Related: #312 (the measure ic reachability gap the trace opacity compounded).

Introspection surfaces

Self-explanation extends past the help text to the introspection commands: every closed vocabulary the engine ships would be listable from the binary, each entry carrying a one-line meaning. Current state, measured against the release binary (2026-07-23):

Vocabulary Listing Meaning per entry
process/campaign blocks process introspect --vocabulary, campaign introspect --vocabulary yes — real doc-strings ("std::gate — filter survivors by a conjunction of typed metric predicates"); the in-repo bar to meet
metrics process introspect --metrics applicability tags only ("sqn_normalized — rankable, gate, generalize"); no meaning text
nodes graph introspect --vocabulary bare names only; --node <NODE> adds ports and param kinds but no semantics ("EMA: in series:F64, out value:F64, param length:I64" — nothing states what Latch, When, Select, Bias do)
taps enumerable indirectly via campaign introspect --block std::presentation (slot enum: equity, exposure, r_equity, net_r_equity) no meaning text
tap folds none — the fold vocabulary (Sum, Mean, Min, Max, Count, First, Last; bind rules; output kinds) exists only as source comments (crates/aura-std/src/tap_fold.rs:13-44), invisible from the binary none

The fold row is additionally moot for a data-plane author today: folds are Rust-only until #310 (the Named fold subscription's data-authorability boundary) settles, and the retired document slot "folds" is explicitly refused (crates/aura-research/src/lib.rs:1959-1962). Whichever way #310 lands, the fold vocabulary needs an introspection surface with doc-strings, as the block vocabulary already has.

Scaffolded project docs

The same duty applies to what aura new / aura nodes new write into a fresh project: the scaffolded project CLAUDE.md carries run/sweep/native-node mechanics but nothing on the execution semantics (bias as continuously-held target, protective stop, the signal-side latch/edge-pulse idiom) that the 2026-07-22 field agent had to discover forensically. One or two sentences there reach every agent that opens a scaffolded project, independent of the help text.

`aura --help` is a flat list of 16 verbs. `process` ("methodology") and `campaign` ("experiment intent") sit unexplained beside the research verbs; nothing states that `run`/`sweep`/`walkforward`/`mc`/`generalize` are sugar over the same registered document kinds, that the data plane is directly authorable, what the bias-as-target-position execution semantics are, or how a persisted trace comes to exist. For a reader without access to this repository — the exact situation of a downstream agent — the help is the only always-present self-description the binary has, and today it describes nothing but the verb inventory. Field evidence (2026-07-22 external field test, triaged in #314): the agent drove the whole day through the sugar verbs and reached the data plane only as an escape hatch after forensics — in one workspace, two failed signal-side workaround blueprints (file mtimes 12:59-13:05) precede the first hand-authored data-plane documents (13:06 a minimal process document, 13:16 a campaign overriding the risk block to disable the protective stop), whose schemas were reverse-engineered by introspecting the CAS artifacts under `runs/`, not learned from the help. Once discovered, the layer carried real work — `aura campaign validate`/`register`/`run`/`introspect` were invoked 27/20/16/13 times across the day's sessions — so the gap is discoverability, not capability. Direction: - The top-level help opens with a short concepts paragraph: the two layers (research verbs as sugar writing registered process/campaign documents; the data plane directly authorable via `aura process` / `aura campaign`), one sentence on the bias-as-target-position + protective-stop execution model, and one on how traces are produced and consumed (`sweep --real --trace` / `walkforward --real --trace` -> `chart` / `measure`). - Each sugar verb's long help names the document kind it desugars to. - The error messages already model the target register (the `--trace` refusals name #224 and point to the verbs that work); the help text would meet that same bar. The generated agent bootstrap card (#267) remains the richer onboarding artifact; the help is the zero-setup surface that exists even when no card was generated. Related: #312 (the `measure ic` reachability gap the trace opacity compounded). ## Introspection surfaces Self-explanation extends past the help text to the introspection commands: every closed vocabulary the engine ships would be listable from the binary, each entry carrying a one-line meaning. Current state, measured against the release binary (2026-07-23): | Vocabulary | Listing | Meaning per entry | |---|---|---| | process/campaign blocks | `process introspect --vocabulary`, `campaign introspect --vocabulary` | yes — real doc-strings ("std::gate — filter survivors by a conjunction of typed metric predicates"); the in-repo bar to meet | | metrics | `process introspect --metrics` | applicability tags only ("sqn_normalized — rankable, gate, generalize"); no meaning text | | nodes | `graph introspect --vocabulary` | bare names only; `--node <NODE>` adds ports and param kinds but no semantics ("EMA: in series:F64, out value:F64, param length:I64" — nothing states what `Latch`, `When`, `Select`, `Bias` do) | | taps | enumerable indirectly via `campaign introspect --block std::presentation` (slot enum: equity, exposure, r_equity, net_r_equity) | no meaning text | | tap folds | none — the fold vocabulary (Sum, Mean, Min, Max, Count, First, Last; bind rules; output kinds) exists only as source comments (`crates/aura-std/src/tap_fold.rs:13-44`), invisible from the binary | none | The fold row is additionally moot for a data-plane author today: folds are Rust-only until #310 (the `Named` fold subscription's data-authorability boundary) settles, and the retired document slot `"folds"` is explicitly refused (`crates/aura-research/src/lib.rs:1959-1962`). Whichever way #310 lands, the fold vocabulary needs an introspection surface with doc-strings, as the block vocabulary already has. ## Scaffolded project docs The same duty applies to what `aura new` / `aura nodes new` write into a fresh project: the scaffolded project CLAUDE.md carries run/sweep/native-node mechanics but nothing on the execution semantics (bias as continuously-held target, protective stop, the signal-side latch/edge-pulse idiom) that the 2026-07-22 field agent had to discover forensically. One or two sentences there reach every agent that opens a scaffolded project, independent of the help text.
claude added the feature label 2026-07-23 12:16:08 +02:00
claude added this to the Self-description — every surface explains itself milestone 2026-07-23 13:42:57 +02:00
claude self-assigned this 2026-07-24 09:41:33 +02:00
claude commented 2026-07-24 10:04:16 +02:00
Author
Collaborator
Copy Link
Copy Source

Shipped on branch worktree-issue-315-help-self-description (829a198) — decision log

Cycle ran without the skills pipeline (owner-directed experiment, 2026-07-24): no spec/plan artifacts — the issue bodies of #315/#323 plus the ratified #319 direction were the spec; derived decisions below were made inline.

  • Fold introspection surface -> aura graph introspect --folds. Folds bind at graph-declared taps (C27), so the graph namespace is their discovery surface; a document-side home would advertise vocabulary the document layer explicitly refuses pending #310. The rows live in aura-std (fold_vocabulary()), prose-pinned by unit test against fold_binds_at/fold_output_kind, doc_gate-checked (C29 entry seam).
  • run --help claims no desugaring. Unlike sweep/walkforward/mc/generalize, run is not verb_sugar-bridged, so its long help points at the canonical document-first form instead of asserting a translation it does not perform. If #319's retirement rewires run, the help line follows.
  • #319 scope applied: no doc-strings for the quintet's flag fields (throwaway under retirement); the per-verb "desugars to " pointer lines are the deliberate bridge toward the document layer.
  • Metrics/taps meanings were data-complete since #316 (metric_vocabulary/tap_vocabulary already carry doc) — the gap was presentation-only. --metrics now prints the doc column; --block std::presentation lists the four tap meanings under the persist_taps slot.
  • Scaffolded project CLAUDE.md teaches the execution model (bias as continuously-held target position, protective stop defines R) and the document ramp (introspect --unwired from a bare {}).

Verification: full workspace suite green, clippy -D warnings clean, aura-bench exit 0 with all fingerprints OK (help_ms +1.6%, in tolerance), cargo doc warning count unchanged. 9 new e2e pins (tests/help_self_description.rs) + scaffold/guide/fold unit pins. Merge into main is the owner's ratification act; closes #315 fires on that push.

## Shipped on branch `worktree-issue-315-help-self-description` (829a198) — decision log Cycle ran without the skills pipeline (owner-directed experiment, 2026-07-24): no spec/plan artifacts — the issue bodies of #315/#323 plus the ratified #319 direction were the spec; derived decisions below were made inline. - **Fold introspection surface -> `aura graph introspect --folds`.** Folds bind at graph-declared taps (C27), so the graph namespace is their discovery surface; a document-side home would advertise vocabulary the document layer explicitly refuses pending #310. The rows live in aura-std (`fold_vocabulary()`), prose-pinned by unit test against `fold_binds_at`/`fold_output_kind`, doc_gate-checked (C29 entry seam). - **`run --help` claims no desugaring.** Unlike sweep/walkforward/mc/generalize, `run` is not verb_sugar-bridged, so its long help points at the canonical document-first form instead of asserting a translation it does not perform. If #319's retirement rewires run, the help line follows. - **#319 scope applied:** no doc-strings for the quintet's flag fields (throwaway under retirement); the per-verb "desugars to <process shape>" pointer lines are the deliberate bridge toward the document layer. - **Metrics/taps meanings were data-complete since #316** (`metric_vocabulary`/`tap_vocabulary` already carry `doc`) — the gap was presentation-only. `--metrics` now prints the doc column; `--block std::presentation` lists the four tap meanings under the persist_taps slot. - **Scaffolded project CLAUDE.md** teaches the execution model (bias as continuously-held target position, protective stop defines R) and the document ramp (`introspect --unwired` from a bare `{}`). Verification: full workspace suite green, clippy -D warnings clean, aura-bench exit 0 with all fingerprints OK (help_ms +1.6%, in tolerance), cargo doc warning count unchanged. 9 new e2e pins (`tests/help_self_description.rs`) + scaffold/guide/fold unit pins. Merge into main is the owner's ratification act; `closes #315` fires on that push.
claude commented 2026-07-24 10:21:03 +02:00
Author
Collaborator
Copy Link
Copy Source

Independent review addendum (2026-07-24)

After the owner asked how the skills-less cycle knows it made no error, two further passes ran on the branch:

  1. Self-audit of prose claims against source -> found + fixed (162bf84): the concepts paragraph claimed run writes registered documents; dispatch_run has no document path — only the four verb_sugar bridges do. The paragraph now names sweep/walkforward/mc/generalize and places run as the single-backtest sibling.
  2. Independent fresh-context review (opus, read-only) over the full branch diff -> verdict changes_requested with 1 Minor + 1 Nit, both adjudicated and fixed (d26f0c8): the desugaring claims now carry the --real qualifier (the synthetic sweep/walkforward/mc branches execute in-process and register nothing; generalize keeps the unconditional wording — its only mode is --real), and the vocabulary listing's silent bare-row fallback became a loud expect. The reviewer verified the OP_REFERENCE field names against the op DTO (all nine accurate) and confirmed the fold-vocabulary and guide-pin anti-drift designs.

Branch state: 3 commits (829a198, 162bf84, d26f0c8) on 6fb7caf; full workspace suite, clippy -D warnings, and bench all green after each fix. Merge = owner ratification.

## Independent review addendum (2026-07-24) After the owner asked how the skills-less cycle knows it made no error, two further passes ran on the branch: 1. **Self-audit of prose claims against source** -> found + fixed (162bf84): the concepts paragraph claimed `run` writes registered documents; `dispatch_run` has no document path — only the four verb_sugar bridges do. The paragraph now names sweep/walkforward/mc/generalize and places run as the single-backtest sibling. 2. **Independent fresh-context review (opus, read-only) over the full branch diff** -> verdict changes_requested with 1 Minor + 1 Nit, both adjudicated and fixed (d26f0c8): the desugaring claims now carry the `--real` qualifier (the synthetic sweep/walkforward/mc branches execute in-process and register nothing; generalize keeps the unconditional wording — its only mode is --real), and the vocabulary listing's silent bare-row fallback became a loud expect. The reviewer verified the OP_REFERENCE field names against the op DTO (all nine accurate) and confirmed the fold-vocabulary and guide-pin anti-drift designs. Branch state: 3 commits (829a198, 162bf84, d26f0c8) on 6fb7caf; full workspace suite, clippy -D warnings, and bench all green after each fix. Merge = owner ratification.
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 feature
Milestone
No items
No Milestone Self-description — every surface explains itself
Projects
Clear projects
No project
Assignees
Clear assignees
claude (Claude) Brummel
No Assignees claude
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Brummel/Aura#315
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?