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

Complete the document-first migration: the run quintet's residual flags become document vocabulary #300

New Issue
Closed
opened 2026-07-21 10:18:44 +02:00 by claude · 5 comments
claude commented 2026-07-21 10:18:44 +02:00
Collaborator
Copy Link
Copy Source

Motivation

The #295 evaluation fixed the control-surface layering (C25 amendment, 2026-07-20: the text artifact vocabulary is the canonical layer; every control surface — executor verbs, a future host, an MCP face, a World program — is a projection/executor over those artifacts, never a second home for intent). The open direction fork — which projection is built next — was decided by the owner for the document-first completion (2026-07-21, minuted on #295): complete the document vocabulary first; any later host or MCP face would wrap the same completed vocabulary, so this work is the prerequisite of every successor surface.

Scope

Migrate the run quintet's residual flag vocabulary into document vocabulary, completing the #210 verb-dissolution line: --axis, --from/--to, --stop-length/--stop-k, --select, --block-len, --resamples, --seeds. The quintet verbs reduce to thin executors over generated documents; the CLI converges on a small executor verb set.

Context

  • The document field shapes (where each flag lands in the campaign/process vocabulary, and what stays an invocation-level concern) are this cycle's design work — deliberately not settled in this issue.
  • The host-vs-MCP ranking beyond this step stays demand-driven: deliberately unranked until a concrete consumer (the C22 local server, a real World program) forces the choice.
## Motivation The #295 evaluation fixed the control-surface layering (C25 amendment, 2026-07-20: the text artifact vocabulary is the canonical layer; every control surface — executor verbs, a future host, an MCP face, a World program — is a projection/executor over those artifacts, never a second home for intent). The open direction fork — which projection is built next — was decided by the owner for the document-first completion (2026-07-21, minuted on #295): complete the document vocabulary first; any later host or MCP face would wrap the same completed vocabulary, so this work is the prerequisite of every successor surface. ## Scope Migrate the run quintet's residual flag vocabulary into document vocabulary, completing the #210 verb-dissolution line: `--axis`, `--from`/`--to`, `--stop-length`/`--stop-k`, `--select`, `--block-len`, `--resamples`, `--seeds`. The quintet verbs reduce to thin executors over generated documents; the CLI converges on a small executor verb set. ## Context - The document field shapes (where each flag lands in the campaign/process vocabulary, and what stays an invocation-level concern) are this cycle's design work — deliberately not settled in this issue. - The host-vs-MCP ranking beyond this step stays demand-driven: deliberately unranked until a concrete consumer (the C22 local server, a real World program) forces the choice.
claude added the feature label 2026-07-21 10:19:02 +02:00
claude self-assigned this 2026-07-21 10:19:02 +02:00
claude commented 2026-07-21 10:36:44 +02:00
Author
Collaborator
Copy Link
Copy Source

Carried from #227 (closed as superseded by this issue): when the select field's document shape is designed here, consider whether a bare plateau value should default its aggregation to mean — the ergonomics ask #227 recorded against the CLI parser. The document vocabulary's current mirror (SelectRule, crates/aura-research/src/lib.rs) keeps the same strict grammar (argmax | plateau:mean | plateau:worst).

Carried from #227 (closed as superseded by this issue): when the select field's document shape is designed here, consider whether a bare `plateau` value should default its aggregation to `mean` — the ergonomics ask #227 recorded against the CLI parser. The document vocabulary's current mirror (`SelectRule`, crates/aura-research/src/lib.rs) keeps the same strict grammar (argmax | plateau:mean | plateau:worst).
claude commented 2026-07-21 10:53:09 +02:00
Author
Collaborator
Copy Link
Copy Source

Design triage for this cycle (2026-07-21)

A five-stance grounded design swarm (minimalist / power-user-composability / maintainer / skeptic / off-ledger wildcard) populated the load-bearing forks of the document-first completion. Each fork below is a derived orchestrator decision carrying its cited shared ground. Established baseline (recon, re-verified against the tree): on the --real/campaign arm every residual flag ALREADY translates into a document field (--axis -> StrategyEntry.axes; stops -> CampaignDoc.risk; --from/--to -> DataSection.windows; --select/MC knobs -> StageBlock; --seed -> CampaignDoc.seed; crates/aura-cli/src/verb_sugar.rs translators); the synthetic (non---real) arms and mc --seeds bypass documents entirely (flags flow straight to aura-runner family builders, stop hardcoded); aura campaign run <target> [--parallel-instruments] is the shipped flagless executor precedent.

  • F1 — the synthetic arm stays verb-wired; no synthetic document vocabulary this cycle. Ground: the #210 realization ratified exactly this split ("built-in/synthetic branches stay verb-wired until #159", docs/design/INDEX.md ~2851-2853), and #159 is gated on #157, so retirement cannot land here. The power-user lens read #225 as pull toward document-mediating the synthetic arm; #225 asks for internal select->optimize dispatch consolidation between library crates — compatible with a verb-wired surface, and it stays its own issue. Noted for any future mediation: the synthetic MC vocabulary must stay distinct from the real bootstrap MC (#106 fork A — different statistical primitives).
  • F2 — executor flags are the doc target + --parallel-instruments only; CampaignDoc.seed suffices, no invocation-level seed override. Ground: the shipped executor grammar (crates/aura-cli/src/research_docs.rs:330-344); the glossary's "campaign run" entry ("deterministic from doc + stores + data (C1): ... seed from the doc's seed"); the translate_* content-id collision tests pin that a seed/stop change changes document identity — an argv override would let a run diverge from its own stored id.
  • F3 — the sugar verbs are pure document generators; no doc+flag-override mode. Ground: the C25 amendment ("never a second home for intent"); the #231 bindings precedent in verb_sugar.rs (generated and authored documents are disjoint populations, never merged by precedence); #210's cure of shell-history evaporation.
  • F4 — run stays a direct executor; not document-mediated. Ground: #300's scope list names none of run's flags; the glossary's atomic sim unit is distinct from a campaign. (Noted as a future option, not decided: run as a degenerate single-member campaign for compositional parity.)
  • F5 — mc --seeds gets no document form this cycle — follows F1; the synthetic seed family is the synthetic arm's own knob.
  • F6 — the stop-knob grammar is unified during the migration, conditional on semantics. Ground: the cross-verb knob-asymmetry class was already adjudicated a defect and its issue closed (#217), so no open home remains, and this cycle rewrites each verb's argv->doc translation anyway. Condition to verify at spec time: whether the walkforward/mc CSV form carries a multi-regime risk axis (CampaignDoc.risk is a Vec — the structural matrix dimension) that generalize's typed single pair cannot express; the unified grammar must preserve that axis capacity, so the concrete form follows the verified semantics.
  • F7 — a bare plateau select value defaults to plateau:mean. Ground: #227's own text proposes exactly this ("the documented default aggregation, mirroring how the stop flags default since #217"), carried onto this issue at #227's close; three lenses converged. The wildcard's counter-reading of C25's forbids-clause fails against a documented default (it forbids implicit holes, not documented defaults).
  • F8 — the verb identities survive this cycle: the quintet verbs stay as thin per-verb generators; no collapse into a compose+run pair. This fork was raised unprompted by three lenses (is "a small executor verb set" four thin verbs, or a genuine verb-count reduction?). Decided on: the per-verb dissolved form was ratified at the #210 milestone close (fieldtest 2026-07-07; ledger ~2862-2864); the owner's direction decision (2026-07-21, minuted on #295) chose "the quintet verbs reduce to thin executors over generated documents" — reduction, not grammar collapse; and the risk asymmetry — keeping the verbs forecloses nothing (a compose/run pair remains an additive later step under demand), while collapsing now breaks a ratified grammar no source asks to break. Recorded prominently because two lenses flagged it as potentially the owner's call: a derived decision, veto-able as every other.

Two surfaced concerns adopted into the cycle's scope:

  • Registered-document round-trip gap (power-user lens): aura campaign {validate,introspect,register,run,runs} cannot export a registered document by content id back to editable JSON (crates/aura-cli/src/research_docs.rs:314-344 — introspect is file-only), undercutting the "durable, diffable" promise of verb_sugar.rs's own module doc. A read/export executor verb joins this cycle's scope as part of settling the executor verb set.
  • Stop-default quadruplication (maintainer lens): StopRule::Vol { R_SMA_STOP_LENGTH, R_SMA_STOP_K } is hand-copied at four crates/aura-runner/src/family.rs sites — collapsed to one named default as a small tidy in this cycle.

Status: design settled — ready for spec production.

## Design triage for this cycle (2026-07-21) A five-stance grounded design swarm (minimalist / power-user-composability / maintainer / skeptic / off-ledger wildcard) populated the load-bearing forks of the document-first completion. Each fork below is a derived orchestrator decision carrying its cited shared ground. Established baseline (recon, re-verified against the tree): on the `--real`/campaign arm every residual flag ALREADY translates into a document field (`--axis` -> `StrategyEntry.axes`; stops -> `CampaignDoc.risk`; `--from/--to` -> `DataSection.windows`; `--select`/MC knobs -> `StageBlock`; `--seed` -> `CampaignDoc.seed`; crates/aura-cli/src/verb_sugar.rs translators); the synthetic (non-`--real`) arms and `mc --seeds` bypass documents entirely (flags flow straight to aura-runner family builders, stop hardcoded); `aura campaign run <target> [--parallel-instruments]` is the shipped flagless executor precedent. - **F1 — the synthetic arm stays verb-wired; no synthetic document vocabulary this cycle.** Ground: the #210 realization ratified exactly this split ("built-in/synthetic branches stay verb-wired until #159", docs/design/INDEX.md ~2851-2853), and #159 is gated on #157, so retirement cannot land here. The power-user lens read #225 as pull toward document-mediating the synthetic arm; #225 asks for internal select->optimize dispatch consolidation between library crates — compatible with a verb-wired surface, and it stays its own issue. Noted for any future mediation: the synthetic MC vocabulary must stay distinct from the real bootstrap MC (#106 fork A — different statistical primitives). - **F2 — executor flags are the doc target + `--parallel-instruments` only; `CampaignDoc.seed` suffices, no invocation-level seed override.** Ground: the shipped executor grammar (crates/aura-cli/src/research_docs.rs:330-344); the glossary's "campaign run" entry ("deterministic from doc + stores + data (C1): ... seed from the doc's `seed`"); the translate_* content-id collision tests pin that a seed/stop change changes document identity — an argv override would let a run diverge from its own stored id. - **F3 — the sugar verbs are pure document generators; no doc+flag-override mode.** Ground: the C25 amendment ("never a second home for intent"); the #231 bindings precedent in verb_sugar.rs (generated and authored documents are disjoint populations, never merged by precedence); #210's cure of shell-history evaporation. - **F4 — `run` stays a direct executor; not document-mediated.** Ground: #300's scope list names none of run's flags; the glossary's atomic sim unit is distinct from a campaign. (Noted as a future option, not decided: run as a degenerate single-member campaign for compositional parity.) - **F5 — `mc --seeds` gets no document form this cycle** — follows F1; the synthetic seed family is the synthetic arm's own knob. - **F6 — the stop-knob grammar is unified during the migration, conditional on semantics.** Ground: the cross-verb knob-asymmetry class was already adjudicated a defect and its issue closed (#217), so no open home remains, and this cycle rewrites each verb's argv->doc translation anyway. Condition to verify at spec time: whether the walkforward/mc CSV form carries a multi-regime risk axis (`CampaignDoc.risk` is a Vec — the structural matrix dimension) that generalize's typed single pair cannot express; the unified grammar must preserve that axis capacity, so the concrete form follows the verified semantics. - **F7 — a bare `plateau` select value defaults to `plateau:mean`.** Ground: #227's own text proposes exactly this ("the documented default aggregation, mirroring how the stop flags default since #217"), carried onto this issue at #227's close; three lenses converged. The wildcard's counter-reading of C25's forbids-clause fails against a documented default (it forbids implicit holes, not documented defaults). - **F8 — the verb identities survive this cycle: the quintet verbs stay as thin per-verb generators; no collapse into a compose+run pair.** This fork was raised unprompted by three lenses (is "a small executor verb set" four thin verbs, or a genuine verb-count reduction?). Decided on: the per-verb dissolved form was ratified at the #210 milestone close (fieldtest 2026-07-07; ledger ~2862-2864); the owner's direction decision (2026-07-21, minuted on #295) chose "the quintet verbs reduce to thin executors over generated documents" — reduction, not grammar collapse; and the risk asymmetry — keeping the verbs forecloses nothing (a compose/run pair remains an additive later step under demand), while collapsing now breaks a ratified grammar no source asks to break. Recorded prominently because two lenses flagged it as potentially the owner's call: a derived decision, veto-able as every other. Two surfaced concerns adopted into the cycle's scope: - **Registered-document round-trip gap (power-user lens):** `aura campaign {validate,introspect,register,run,runs}` cannot export a registered document by content id back to editable JSON (crates/aura-cli/src/research_docs.rs:314-344 — introspect is file-only), undercutting the "durable, diffable" promise of verb_sugar.rs's own module doc. A read/export executor verb joins this cycle's scope as part of settling the executor verb set. - **Stop-default quadruplication (maintainer lens):** `StopRule::Vol { R_SMA_STOP_LENGTH, R_SMA_STOP_K }` is hand-copied at four crates/aura-runner/src/family.rs sites — collapsed to one named default as a small tidy in this cycle. Status: design settled — ready for spec production.
claude commented 2026-07-21 11:12:48 +02:00
Author
Collaborator
Copy Link
Copy Source

Spec auto-signed (2026-07-21)

The cycle's spec — the document-first completion keystone: a show read-back executor verb over the existing registry get API, typed stop knobs on walkforward/mc (three named tests adapted in the same change), bare plateau defaulting to plateau:mean, the DEFAULT_STOP tidy in the assembly crate, and two ledger amendments (the C25 "which projection next" line resolved; a C18 read-back realization note) — was signed autonomously. The signature is an independent fresh-context grounding check returning PASS: all ten load-bearing assumptions about current codebase behaviour were ratified against currently-green tests.

Process note: a first grounding dispatch returned BLOCK on three spec factual defects — a wrongly-denied test pin (three green tests DO pin the old bespoke stop error), a nonexistent ledger anchor (no "#206" paragraph in C18), and a misnamed helper (Env::registry(), not registry_for). The checker's own findings supplied the corrections; the spec was fixed in place and a fresh dispatch passed. No human signed; the owner was notified and retains a veto.

Non-blocking snippet notes carried into planning: parse_select returns Selection::Plateau(PlateauMode::Mean) (mapped to the document's SelectRule by select_rule_of, crates/aura-cli/src/main.rs:503), and Env::registry() returns Registry directly, not Result.

## Spec auto-signed (2026-07-21) The cycle's spec — the document-first completion keystone: a `show` read-back executor verb over the existing registry get API, typed stop knobs on walkforward/mc (three named tests adapted in the same change), bare `plateau` defaulting to `plateau:mean`, the DEFAULT_STOP tidy in the assembly crate, and two ledger amendments (the C25 "which projection next" line resolved; a C18 read-back realization note) — was signed autonomously. The signature is an independent fresh-context grounding check returning PASS: all ten load-bearing assumptions about current codebase behaviour were ratified against currently-green tests. Process note: a first grounding dispatch returned BLOCK on three spec factual defects — a wrongly-denied test pin (three green tests DO pin the old bespoke stop error), a nonexistent ledger anchor (no "#206" paragraph in C18), and a misnamed helper (`Env::registry()`, not `registry_for`). The checker's own findings supplied the corrections; the spec was fixed in place and a fresh dispatch passed. No human signed; the owner was notified and retains a veto. Non-blocking snippet notes carried into planning: `parse_select` returns `Selection::Plateau(PlateauMode::Mean)` (mapped to the document's `SelectRule` by `select_rule_of`, crates/aura-cli/src/main.rs:503), and `Env::registry()` returns `Registry` directly, not `Result`.
claude commented 2026-07-21 12:58:10 +02:00
Author
Collaborator
Copy Link
Copy Source

Audit close (2026-07-21)

Architect drift review over the cycle commit: core clean (C28 — show is pure shell dispatch over the registry API; C25/C18 amendments match the F1-F8 decision log; document schema untouched). Four peripheral items resolved in the audit commit: the authoring-guide and glossary verb rosters caught up to the settled verb set; show_process's refusal prose single-sourced onto ref_fault_prose; and one deliberate deviation ratified here for the record — the shipped show helpers print with no trailing-newline framing (print!, the #164 transport rule, mirroring graph_construct::build_cmd) where the spec's illustrative snippet sketched println!; the code is the stricter form, and the round-trip tests pin the exact stored bytes, which is stronger than the spec required.

Regression: the report-only bench ran green — all fingerprints OK, every lane within noise (host load 9.6 noted). Full workspace verification at the cycle commit: 1482 passed / 0 failed, clippy -D warnings clean, with the GER40-gated round-trip tests genuinely exercised.

## Audit close (2026-07-21) Architect drift review over the cycle commit: core clean (C28 — `show` is pure shell dispatch over the registry API; C25/C18 amendments match the F1-F8 decision log; document schema untouched). Four peripheral items resolved in the audit commit: the authoring-guide and glossary verb rosters caught up to the settled verb set; `show_process`'s refusal prose single-sourced onto `ref_fault_prose`; and one deliberate deviation ratified here for the record — the shipped `show` helpers print with **no trailing-newline framing** (`print!`, the #164 transport rule, mirroring `graph_construct::build_cmd`) where the spec's illustrative snippet sketched `println!`; the code is the stricter form, and the round-trip tests pin the exact stored bytes, which is stronger than the spec required. Regression: the report-only bench ran green — all fingerprints OK, every lane within noise (host load 9.6 noted). Full workspace verification at the cycle commit: 1482 passed / 0 failed, clippy -D warnings clean, with the GER40-gated round-trip tests genuinely exercised.
claude commented 2026-07-21 13:31:35 +02:00
Author
Collaborator
Copy Link
Copy Source

Cycle outcome (2026-07-21)

The document-first cycle shipped on the branch worktree-issue-300-document-first, unmerged, awaiting review — five commits above the anchor 4ed6455:

  • 757e3ac — the keystone: aura process|campaign show <content-id> (canonical bytes, no framing — #164), typed --stop-length/--stop-k on walkforward/mc (three pinning tests adapted, stop_knob_or/parse_csv_list deleted), bare plateau as the documented plateau:mean default (#227 carry, content-id-identical, test-pinned), the DEFAULT_STOP constant fold, and the two ledger amendments (C25 direction line resolved; C18 read-back note).
  • a12617b — audit close: architect core-clean; authoring-guide/glossary verb rosters caught up; show_process refusal prose single-sourced; the print!-over-println! deviation ratified on this log.
  • 63711a1 — fieldtest corpus: four downstream-author examples over the real GER40 archive; all four axes hold (the closed generate → show → hand-extend → re-register → run loop ran end-to-end, first try, from public docs alone).
  • 803c970 + da37f59 — the fieldtest's one bug, RED-first: show outside a project now names the missing Aura.toml instead of blaming the id (#304).

Verification at head: full workspace suite 1483 passed / 0 failed, clippy -D warnings clean; report-only bench green (all fingerprints OK).

Filed forward during the close: #301 (opaque document-select refusal), #302 (show prefix-id ergonomics), #303 (broken ger40-lab fixture paths, found orthogonally), #305 (register creates a stray store outside a project, found during diagnosis). The fieldtest spec survives git-ignored as the next planning cycle's reference input.

Status: work complete and gated; the branch awaits review and the ratified merge (which will close this issue and #304 via the commit trailers).

## Cycle outcome (2026-07-21) The document-first cycle shipped on the branch `worktree-issue-300-document-first`, unmerged, awaiting review — five commits above the anchor `4ed6455`: - `757e3ac` — the keystone: `aura process|campaign show <content-id>` (canonical bytes, no framing — #164), typed `--stop-length`/`--stop-k` on walkforward/mc (three pinning tests adapted, `stop_knob_or`/`parse_csv_list` deleted), bare `plateau` as the documented `plateau:mean` default (#227 carry, content-id-identical, test-pinned), the `DEFAULT_STOP` constant fold, and the two ledger amendments (C25 direction line resolved; C18 read-back note). - `a12617b` — audit close: architect core-clean; authoring-guide/glossary verb rosters caught up; `show_process` refusal prose single-sourced; the `print!`-over-`println!` deviation ratified on this log. - `63711a1` — fieldtest corpus: four downstream-author examples over the real GER40 archive; all four axes hold (the closed generate → show → hand-extend → re-register → run loop ran end-to-end, first try, from public docs alone). - `803c970` + `da37f59` — the fieldtest's one bug, RED-first: `show` outside a project now names the missing Aura.toml instead of blaming the id (#304). Verification at head: full workspace suite 1483 passed / 0 failed, clippy `-D warnings` clean; report-only bench green (all fingerprints OK). Filed forward during the close: #301 (opaque document-select refusal), #302 (`show` prefix-id ergonomics), #303 (broken ger40-lab fixture paths, found orthogonally), #305 (`register` creates a stray store outside a project, found during diagnosis). The fieldtest spec survives git-ignored as the next planning cycle's reference input. Status: work complete and gated; the branch awaits review and the ratified merge (which will close this issue and #304 via the commit trailers).
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
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#300
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?