Ship a generated agent bootstrap card #267
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?
An agent operating aura in deployment posture (docs + CLI, no engine sources) needs a compact, current self-description of the authoring surface: the node vocabulary with port/param tables, the op-script grammar, the process/campaign document schemas, the metric roster, and the unit/semantic notes of #265.
Evidence that this is sufficient: a hand-distilled ~150-line card with exactly that content, plus the CLI validation loop (
graph build,introspect --params, three-tiercampaign validate), was the entire aura knowledge of six engine-blind agents that each authored a blueprint family — 6/6 built and validated green on the first run attempt (2026-07-13, engine84e1075).Everything in such a card except the semantic notes is already introspectable verb by verb, so a
aura graph introspect --agent-card-style verb (or a doc artifact generated from the same rosters, so it cannot drift) would productize it. The archive inventory (#264) is the remaining piece an authoring agent cannot introspect today.Re-anchoring this issue against the #295 shell-boundary cut and the #300 document-first direction.
Both prerequisites this issue named as blocking are now closed and delivered:
aura data listandaura data coverage(DataCommand::List / DataCommand::Coverage, crates/aura-cli/src/main.rs) enumerate instruments and m1 coverage from the monthly file index.The remaining ask — an actual generated agent bootstrap card — is not yet built; no
--agent-card-styleflag or equivalent generator exists in the tree.Two other things moved since this issue was filed and should inform how it is closed out:
aura graph introspect,aura process validate, andaura campaign validatestill exist as verbs but dispatch through aura_runner::project::Env rather than owning logic directly (crates/aura-cli/src/graph_construct.rs, crates/aura-cli/src/research_docs.rs).Given the C25 control-surface amendment (docs/design/INDEX.md, 'every control surface ... is a projection/executor over [the text-artifact vocabulary], never a second home for intent') and the decided document-first direction (#300, which migrates the run quintet's residual flags into document vocabulary and converges the CLI on a small executor verb set), the generated-doc-artifact option this issue already proposed as an alternative to a new CLI flag is now the better-aligned realization: a card assembled from the same rosters (node vocabulary via aura-vocabulary, metric roster via aura-measurement, cost/risk units via the campaign introspect annotations from #265, archive inventory via #264) as a text artifact, rather than a new
--agent-card-styleflag bolted ontoaura graph introspect. Scoping this as a generated-artifact deliverable keeps it consistent with #300's trajectory instead of adding a one-off CLI flag the convergence would later need to unwind.Field evidence for what the bootstrap card must cover — from the 2026-07-22 external field test (an LLM agent driving the release binary with no source or docs access; triage in #314):
Bias-as-target-position semantics. The agent read the risk executor's stop-then-reopen behaviour under a continuous bias as an engine defect ("broker re-entry loop"), burned a session on two signal-side workarounds — a Delay(1) one-tick pulse (position flattened one cycle later because the bias fell back to 0) and a daily Resample (still a step function, churn persisted) — before converging on latch/edge-pulse patterns. The behaviour is intended (contract C10 / domain invariant 7: the bias is a continuously-held target, the stop a pure protective exit;
crates/aura-backtest/src/position_management.rs:176), but nothing reachable from the binary says so. The card would state the target-position semantics and the signal-side latch/edge-pulse idiom up front.Trace availability. The agent tried
run --trace(hard-refused as retired per #224), concluded that trace persistence is disabled altogether, and abandonedaura measure ic. The card would name the two verbs that do persist traces (sweep --real --trace,walkforward --real --trace); the underlyingmeasure icreachability gap is filed separately as #312.Scope note (user decision, 2026-07-23): once #316 (self-description as a ledger design principle — every surface explains itself) is fully implemented, the bootstrap card's role as a separate external source is to be re-examined — surfaces that explain themselves (help, introspection, scaffolded docs, error messages) may make a generated card partially or wholly redundant. Until then the card remains the richer onboarding artifact, and the field evidence in the field-test comment stands either way.
Closed as superseded (user decision, 2026-07-24)
The re-examination the 2026-07-23 scope note mandated has run its course: with #316 (self-description as a ledger principle, C29), #315 (two-layer CLI help), and #323 (C29 authoring surfaces) merged to main, the card's content is delivered by the surfaces themselves, at the places an agent actually looks first:
sweep --real --trace,walkforward --real --trace).graph introspect --vocabulary/--node), folds (--folds), metrics (process introspect --metrics), document blocks/slots including the description slot (campaign introspect --block/--unwired), and the op grammar (graph build --help).aura data list/aura data coverage(#264).The field evidence collected in this thread stands as the requirements list the surfaces had to satisfy; it is what #315/#316/#323 were built against. Empirical validation of this closure is the binary-only M1 milestone fieldtest (running next): an agent-posture consumer bootstraps from the binary alone, no card. A red finding there reopens this issue or files a targeted successor.
Empirical confirmation — binary-only M1 milestone fieldtest (2026-07-24)
The check announced above ran: a fieldtest agent bootstrapped from the release binary (
d26f0c8) alone — no sources, no repo docs, no card. Verdict: the retired card is genuinely redundant for the bootstrap→author→validate spine. The consumer learned aura from--help, scaffolded a project, discovered every vocabulary with per-entry meanings (33 nodes / 7 folds / 17 metrics / 6+6 document blocks), authored an EMA-cross and the latch/edge-pulse idiom via the op grammar, grew process+campaign documents from a bare{}, and ran green on real EURUSD data — zero recourse to the repo.Residual findings routed to the tracker: #327 (bug: declared taps dropped on the registration path), #328 (sugar↔document axis namespace), #329 (
process.reftagged form), #330 (cost one-liners), #331 (blueprint name default); evidence comments on #312 and #324. Corpus committed underfieldtests/m1-self-description/.Milestone 36 closes on this run: the two seams the fieldtest names are tracked scope of M6 (#312/#327) and the #319 retirement path (#328) — not self-description regressions.