Doc/scaffold polish from the external fieldtest: compiled-tap schema, use-by-label visibility, risk-wiring example, nodes-new hint #346

New Issue

2026-07-26T15:57:48+02:00

claude commented

2026-07-26 15:57:48 +02:00

Source

External source-blind fieldtest (2026-07-26): a non-Claude agent (Gemini) exercised the release binary in a fresh lab, first binary-only, then with docs/authoring-guide.md + docs/glossary.md handed over. The full document-first spine passed (op-script authoring with LinComb + regime filter + registered use splice, sweep → gate → walk_forward → monte_carlo → generalize on two instruments, reproduce 4/4 bit-identical, chart). Every refusal it hit resolved the problem in one step. What remains is doc/scaffold polish — bundled here per the tracker-hygiene convention. Note: the lab ran a pre-2026-07-26-harvest binary, so prose nits may partially be fixed already; each item below names its residue.

Items

Compiled-blueprint taps schema is only mentioned in passing (guide ~line 334). The tester tried three guessed variants before landing on the TapWire object form — first the edges-analogous flat form ("from": 3, "from_field": 0), because the edges section uses exactly those keys. Document the compiled form ({"name":…,"from":{"node":<i>,"field":<k>}}) explicitly, contrast it with the edges form, and state that the canonical way to add taps is the op-script tap op + aura graph build, not hand-editing compiled documents.
Scaffold/guide divergence. aura new ships a COMPILED blueprint (blueprints/signal.json) while the guide teaches op-scripts — so the natural consumer move from the scaffold is hand-patching the compiled artifact (exactly what the tester did, with python). Ship the op-script source beside the compiled example, or point from the scaffold to the op-script path.
use-by-label is not visible enough. The tester reached for use with a local name, got the (good) no labels registered refusal, and then fell back to copy-pasting content ids. register --name + use-by-label exists (#317) but the guide's use section does not lead with it — make the label workflow the worked example. Minuted here as considered-and-REJECTED: file-path use refs (the tester's suggestion) — they would bypass the store and weaken content addressing / reference semantics (C18/C24, #343 revised decision).
Manual risk-wiring worked example. How PositionManagement/stop nodes wire inside a blueprint vs. the campaign harness's automatic risk wrapper, and why there is deliberately no Sizer in the research loop (C10 — money is a deploy-edge concern). The tester expected a Sizer; the absence is a design statement worth one guide paragraph.
nodes new success-message hint. The runtime refusal is already exemplary (project dylib not found at … — run cargo build in the project first (or pass --release …)) and auto-building was explicitly not desired by the tester (scaffold-without-build is idiomatic). The one residue: append to the created node crate … success line a one-line hint that cargo build in the node crate is required before the next aura command touches the project.

Provenance

Lab findings: ~/dev/poc/aura-tests_2/Findings.md (local, outside the repo); conversation evidence for the guessed tap variants in the agy session transcript.

## Source External source-blind fieldtest (2026-07-26): a non-Claude agent (Gemini) exercised the release binary in a fresh lab, first binary-only, then with `docs/authoring-guide.md` + `docs/glossary.md` handed over. The full document-first spine passed (op-script authoring with LinComb + regime filter + registered `use` splice, sweep → gate → walk_forward → monte_carlo → generalize on two instruments, `reproduce` 4/4 bit-identical, chart). Every refusal it hit resolved the problem in one step. What remains is doc/scaffold polish — bundled here per the tracker-hygiene convention. Note: the lab ran a pre-2026-07-26-harvest binary, so prose nits may partially be fixed already; each item below names its residue. ## Items 1. **Compiled-blueprint `taps` schema is only mentioned in passing** (guide ~line 334). The tester tried three guessed variants before landing on the `TapWire` object form — first the edges-analogous flat form (`"from": 3, "from_field": 0`), because the `edges` section uses exactly those keys. Document the compiled form (`{"name":…,"from":{"node":<i>,"field":<k>}}`) explicitly, contrast it with the edges form, and state that the canonical way to add taps is the op-script `tap` op + `aura graph build`, not hand-editing compiled documents. 2. **Scaffold/guide divergence.** `aura new` ships a COMPILED blueprint (`blueprints/signal.json`) while the guide teaches op-scripts — so the natural consumer move from the scaffold is hand-patching the compiled artifact (exactly what the tester did, with python). Ship the op-script source beside the compiled example, or point from the scaffold to the op-script path. 3. **use-by-label is not visible enough.** The tester reached for `use` with a local name, got the (good) `no labels registered` refusal, and then fell back to copy-pasting content ids. `register --name` + use-by-label exists (#317) but the guide's `use` section does not lead with it — make the label workflow the worked example. Minuted here as considered-and-REJECTED: file-path `use` refs (the tester's suggestion) — they would bypass the store and weaken content addressing / reference semantics (C18/C24, #343 revised decision). 4. **Manual risk-wiring worked example.** How PositionManagement/stop nodes wire inside a blueprint vs. the campaign harness's automatic risk wrapper, and why there is deliberately no Sizer in the research loop (C10 — money is a deploy-edge concern). The tester expected a Sizer; the absence is a design statement worth one guide paragraph. 5. **`nodes new` success-message hint.** The runtime refusal is already exemplary (`project dylib not found at … — run `cargo build` in the project first (or pass --release …)`) and auto-building was explicitly not desired by the tester (scaffold-without-build is idiomatic). The one residue: append to the `created node crate …` success line a one-line hint that `cargo build` in the node crate is required before the next aura command touches the project. ## Provenance Lab findings: `~/dev/poc/aura-tests_2/Findings.md` (local, outside the repo); conversation evidence for the guessed tap variants in the agy session transcript.

claude referenced this issue

2026-07-26 20:27:00 +02:00

Embedding-surface polish from the M4 milestone fieldtest: refusal prose, divergence-class doc, entry-point discoverability, scaffold path dep #349

claude commented

2026-07-26 20:27:14 +02:00

Cross-reference (M4 merge, 2026-07-26)

Item 5 here (the missing cargo build hint on the aura nodes new success line) edits the same scaffolder emission as #349 item 5, which found that the scaffold writes an absolute engine path into the generated Cargo.toml — the committed M4 fieldtest fixture had to relativize it by hand. The two are one edit to the scaffolder's output; the doc items of this issue pair with #349 items 3+4 (the divergence exit class and the unnamed embedding entry points).

Details in the consolidation note on #349. No scope change here.

## Cross-reference (M4 merge, 2026-07-26) **Item 5 here** (the missing `cargo build` hint on the `aura nodes new` success line) edits the same scaffolder emission as **#349 item 5**, which found that the scaffold writes an *absolute* engine path into the generated `Cargo.toml` — the committed M4 fieldtest fixture had to relativize it by hand. The two are one edit to the scaffolder's output; the doc items of this issue pair with #349 items 3+4 (the divergence exit class and the unnamed embedding entry points). Details in the consolidation note on #349. No scope change here.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Brummel/Aura#346