Retire the research-verb sugar in favour of document-first authoring over a self-explaining CLI #319
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?
Successor to the direction fork #295 left open (which projection over the canonical document layer is built first) — the radical completion of its "document-first completion" candidate, informed by the post-close field evidence recorded in the field-test comment on #295: retire the research-verb sugar (
run/sweep/walkforward/mc/generalizeas flag surfaces) entirely, in favour of document-first authoring carried by a self-explaining CLI (#316).Why the sugar harms
The classic argument no longer applies: since the verb dissolution (#210) the quintet is pure translation argv → generated campaign document → executor, so intent is persisted, not evaporated. Three harms remain, all evidenced by the 2026-07-22 field test (triage in #314):
--stop-k↔risk.vol.k,--axis↔axes), doubling the #316 documentation duty, the error paths, and the drift risk.What the sugar provides, and its replacement
The sugar is the on-ramp — the field agent was productive within minutes, and with today's help a document-first start would have failed. It is compensation for missing self-explanation, and simultaneously its inhibitor. The replacement ramp:
aura newscaffolds starter documents per methodology; the help opens with the two-layer concept (#315);process/campaign introspect --unwired(grow a document from a bare{}) plus mandatory doc-strings (#316) teach the schema in place. One deliberate sugar residue survives: a bound-param override on the executor verb (the mechanism #246 already defines forrun), recorded in the run manifest — not a second home for intent while the document stays the base.Target verb set (sketch):
new nodes validate register introspect exec <doc> runs reproduce chart measure data— the quintet retired as flag surfaces.Dependency relation to #316
Neither issue blocks the other wholesale; the relation is staged and runs in both directions at different levels:
Resulting order: decide this fork first (cheap, scope-shaping) → implement #316 on the surviving surfaces (documents, executor verbs, help) → execute the retirement → re-run an external field test as the A/B against the 2026-07-22 baseline (does an unprepared agent reach productivity through the document ramp as fast as through the sugar?).
Status: direction not yet decided — the fork is the owner's call; this records the analysis and the dependency shape.
Decision (user, 2026-07-23): the retirement is ratified. The research-verb sugar (
run/sweep/walkforward/mc/generalizeas flag surfaces) will be retired in favour of document-first authoring, per the analysis in the issue body. Rationale as stated: the CLI has no direct human audience — it is driven exclusively by LLM agents and by algorithms/scripts, and both handle the data plane (typed, introspectable documents) better than the argv sugar layer.Scope consequences now in force:
The label moves
idea->feature: the direction is committed, no longer droppable. Execution remains blocked on the #316 document ramp.Direction ratified (owner, 2026-07-24)
Fork: retire the research-verb sugar -> YES. The owner ratified the retirement direction in chat on 2026-07-24. Consequences, per this issue's dependency shape:
pre-sugar-retirement(= main6fb7caf, pushed) marks the last main state with the sugar intact — the A-baseline for that comparison.Triage (2026-07-24)
Milestone container created for the ratified retirement (this issue + #328). Sequence: #328 first — the binary-only M1 fieldtest showed the sugar and document axis namespaces disagree (
graph.<node>.<param>vs<node>.<param>, bound vs open-only), which must be reconciled before the sugar is removed. Related loose end: #331 (blueprint name default) follows whatever #328 decides.Retirement inventory note (from the #331 cycle)
#331 shipped a root-name shape gate over the class "every CLI intake reading an authored blueprint envelope from a file". Held against this issue's target verb set, that class splits — and the retirement should sweep the sugar half out with the verbs:
Dies with the flag quintet (remove the gate call sites and their pins when the verbs go):
run_blueprint_sweep/run_blueprint_walkforward/run_blueprint_mcandvalidate_and_register_axessweep --list-axesgate (list_blueprint_axes) — the discovery function itself survives asgraph introspect --params <FILE>, which keeps its own gateaura_sweep_synthetic_blueprint_refuses_a_hand_crafted_envelope_with_a_bad_root_name,aura_sweep_list_axes_refuses_a_hand_crafted_envelope_with_a_bad_root_nameStays (canonical layer): the
nameop intake,register(the C29-critical store-populating path), theintrospectfile forms, the bare graph-file viewer, and the store-read-back exemption with its ratifying test. Theaura run <FILE>gate migrates to the executor successor (exec <doc>reads the same authored-file intake) rather than dying.Context, recorded for honesty: the sugar-side gates were added by the #331 closing gates enforcing class completeness on the then-live surface; held against this issue's plan they are consistency work on a surface already scheduled for retirement (orchestrator judgement lapse, minuted on the skills tracker as a lesson — the class boundary should have been checked against the roadmap). They are correct and harmless until the retirement lands; nothing needs reverting, only sweeping here.
Design minutes (2026-07-25) — the retirement shape
Eight derived decisions, taken against the ratified direction (the ratification comment of 2026-07-24 on this issue) and the retirement inventory note (issues/319#issuecomment-4716), recorded for audit and veto.
Fork: target verb set → retirement only, no namespace flattening. The five quintet verbs (
run,sweep,walkforward,mc,generalize) retire;exec <target>is the one new top-level verb and replacescampaign run(one executor, no alias). Thegraph/process/campaignnamespaces otherwise stay as they are. The issue body's sketch additionally flattensvalidate/register/introspectto top level and dropsgraph; that part is explicitly a sketch and is NOT taken here. Basis: derived — the ratified decision is the retirement itself; the flattening is separable, carries its own unresolved questions (wheregraph buildlands; how a flatvalidatedisambiguates the document classes), and can be its own later cycle without re-touching the retirement.execcannot staycampaign runbecause it executes more than campaigns (next fork).Fork: what
execexecutes → three target classes. (1) a campaign document file (register-then-run, exactly ascampaign runbehaves today), (2) a 64-hex campaign content id, (3) an authored blueprint envelope file — the single-run successor ofaura run <FILE>, carrying the migrated root-name shape gate per the retirement inventory. The retiredrunverb's no-argument form (the pre-blueprint built-in harness grammar) dies unreplaced: an executable target is always a document. Basis: derived — the inventory records therunintake migrating to the executor successor; the blueprint is itself a canonical document (C24), so a blueprint single run is document-first; the authoring hot-loop keeps its one-command smoke run.Fork:
exec's flag surface → run-mode flags on the blueprint leg only. Campaign/id targets keep exactly--parallel-instruments(the RAM lever). The blueprint leg inheritsrun's run-mode flags unchanged:--params(THE deliberate sugar residue — the bound-param override),--seed,--real/--from/--to(replay data choice),--tap TAP=FOLD(fold selector). These flags are refused on campaign/id targets, pinned by test. Basis: derived — the harm the retirement removes is campaign-document vocabulary in argv form (axes, stops, windows, selection: the other 42 of the 48 fields). On a campaign target,--real/--from/--towould shadow the document'sinstruments/windowfields — hence refused there. On a blueprint target there is no shadowed field: a blueprint deliberately carries no data binding (the data window is an orchestration axis, C12), so the flags are the only home of a binding the executed document intentionally lacks — not a second home for intent. The stricter alternative (only--paramssurvives; every real-data smoke run requires a one-cell campaign document) was weighed and rejected: it removes no duplication on the blueprint leg and degrades the authoring hot-loop the document ramp exists to keep.Fork: override recording → the existing manifest
params/defaultssplit, no new field. A--paramsoverride on the blueprint leg is recorded in the run manifest'sparamsmap (what varied this run); the executed blueprint's own bound values are content-addressed, so the override is reconstructable by construction — for a single run, nothing else varies. Acceptance is pinned by a test asserting the overridden value appears in the manifest line. Basis: derived — the source demands the override be recorded; the existing varied-vs-held split already is that record, and a provenance flag would add schema no query needs.Fork: the zero-trade window note → migrates to the executor's walk-forward presentation. The
aura: note:zero-trade diagnostic currently has only quintet producers and would silently die with them; it moves to the campaign executor's walk-forward output at today's strength. Widening it to sweep/generalize/vacuous-mc remains issue #324, untouched. Basis: derived — the retirement must not silently lose a shipped C14 diagnostic class; smallest honest scope is parity.Fork: orphaned machinery → coverage-preserving retirement.
verb_sugar.rs, the ~67 quintet-only items in the CLI, and the threeaura-runnerfamily builders (blueprint_sweep_family/blueprint_walkforward_family/blueprint_mc_family, which lose their only production caller) retire with the verbs. Any invariant their tests pin that the campaign path does not already pin is ported to the campaign path, not dropped; the plan enumerates this per test.topology_hashstays — its caller is the single-run record line, which theexecblueprint leg emits unchanged. Basis: derived — a dead second execution path is precisely the drift flank this retirement exists to close (the #331 lesson applied at roadmap level); coverage parity keeps the retirement behaviour-honest.Fork: bench surfaces → re-target, expect fingerprint continuity. The fixed-cost probe's minimal run re-targets the executor's blueprint leg; since the record line is unchanged by design, the run-line fingerprint is expected to hold, and any shift is ratified explicitly at cycle close per the audit rules. The campaign bench surfaces re-target the executor verb. Basis: derived — the surface measures spawn+load+single-run fixed cost, which survives a verb rename.
Fork: prose surface → live docs and ledger amend; the fieldtest corpus does not. README verb table, authoring guide, project layout, glossary, the scaffolder's project-template text, and the CLI concepts help are rewritten to the surviving surface; the design ledger is amended as a design decision (C25's executor-verb-set sentence re-settled under the ratified retirement, C14's dual-grammar section reduced to the document grammar plus
exec, C24's gated-intake enumeration and axis-discovery sections narrowed, C12's override clause and identity-anchor location updated, with superseded text moved verbatim to the history sidecars). Thefieldtests/corpus is a frozen historical archive and is not touched. Basis: derived — live docs must describe the shipping surface; ledger edits that change ratified sentences are design amendments under the ledger discipline, and the corpus is a record of past cycles, not live documentation.Design settled — the retirement shape above is ready for spec production. The A/B field comparison against the
pre-sugar-retirementbaseline remains the milestone's closing evidence, per the staged order in the issue body.Fork revision:
exec's flag surface narrowed (2026-07-25)Revises the third fork of the design minutes (issues/319#issuecomment-4746) after an independent adversarial review of the draft spec refuted the wider surface.
Previous derived decision: the
execblueprint leg inherits all six ofrun's run-mode flags (--params,--seed,--real,--from,--to,--tap).Refutation accepted: the only provenance-bearing source sentence is singular — "One deliberate sugar residue survives: a bound-param override on the executor verb" (issue body, re-affirmed in the ratification of 2026-07-23) — and
--real/--from/--to/--seedare campaign-document vocabulary in argv form (instruments,window, seeds), which partially re-opens the issue's harm 3 (the erosion flank).Revised decision: the blueprint leg carries exactly two flags.
--params— the one deliberate residue,run's semantics unchanged (positional Scalar cells closing the signal's open knobs, open-blueprint refusal intact), values recorded in the run manifest'sparamsmap.--tap TAP=FOLD— survives on its own ratified basis, not as part of the residue: the fold selector shipped on the run verb as run-mode authority (issue #310, merged 2026-07-24) — a selection of how a run is observed, not experiment intent; removing it unreplaced would silently regress a just-shipped capability. Its campaign-side carrier remains tracked under #312.--seed/--real/--from/--todie withrun: instrument, window, and seed are document intent; a real-data or seeded single run is a (possibly one-cell) campaign document. Theexecblueprint leg is the synthetic-stream smoke run of the authoring loop.--parallel-instruments;--params/--tapare refused there with prose naming the per-leg rule.Basis: derived — following the literal residue sentence over capability conservatism; the weighing that preferred the wider surface was identified as bias by the adversarial lens, and the narrower surface loses no capability that the document layer does not carry.
Fork revision 2: the residue is
--override, not--params(2026-07-25)Revises the residue decision of issues/319#issuecomment-4749 after the grounding gate found the assumed current behaviour does not exist.
Finding (grounding):
run --paramsis a dead flag today. The dispatch refuses any open blueprint before parsing--params, and a closed blueprint's param arity is zero — so any non-empty--paramsexits 1; no test anywhere invokes it (the gap issue #340 suspected). "Inherit run's--paramssemantics unchanged" therefore inherits nothing: there is no working semantics to carry over.Revised decision: the one deliberate sugar residue on the executor verb is
--override <node>.<param>=<value>(repeatable), on both target classes:paramsmap ("what varied"). Without--overridea blueprint runs fully bound, exactly as today.Consequences:
--paramsdies withrun, unreplaced, together with its decoder; issue #340 (verifyrun --paramscloses free knobs; self-explaining cell shape) is superseded by this design — its subject flag ceases to exist. The blueprint leg ofexecruns fully-bound blueprints on the synthetic stream; every other parameterization is document intent.Basis: derived — the issue's residue sentence names the #246 mechanism, and the #246 mechanism is the axis-over-bound-param reopen path (live and test-ratified on the campaign side), not the dead positional-cell flag; exposing exactly that mechanism as exactly one flag honours the singular residue sentence with machinery that verifiably exists.
Spec auto-signed (2026-07-25)
The design spec for the sugar retirement — the five research verbs retired as flag surfaces; one document executor
execover campaign documents (file or content id) and fully-bound blueprint envelopes, carrying the single--overridebound-param residue and the blueprint-leg--tapselector; the root-name gate and the zero-trade diagnostic migrated to the surviving surface; orphaned translation machinery retired coverage-preservingly; docs, help, scaffolder, and ledger amended — was signed autonomously. The signature is the independent grounding gate's PASS against currently-green tests (13 ratified assumptions, no unratified residue); no human signed. Before the sign, an adversarial scope lens and the grounding gate each forced one fork revision, recorded at issues/319#issuecomment-4749 and issues/319#issuecomment-4752.Minute correction:
topology_hash's survival rationale was wrong (2026-07-25)The orphaned-machinery fork of the design minutes (issues/319#issuecomment-4746) kept the CLI-side
topology_hashhelper on the grounds that "its caller is the single-run record line, which theexecblueprint leg emits unchanged". The removal work disproved that basis: the record line'smanifest.topology_hashis computed inside the runner layer's member machinery, and the CLI helper was never on the single-run print path — its only production caller was the retired axis-registration preflight, and after the quintet removal it is dead in production, kept alive solely by the family-builder unit tests already slated for retirement.Revised decision (derived): the CLI helper retires together with the family-builder tests; the design ledger's identity-anchor references (C12/C18/C24) are amended to name the actual computation site in the runner's member/content-id machinery instead of the CLI shell. The identity mechanism itself is untouched — only the prose pointer and a dead duplicate go.