Trace-surface friction from the #311 field test: handle discoverability, measure-ic parity, pre-run identity, empty-state answers #355

New Issue

2026-07-27T11:38:40+02:00

claude commented

2026-07-27 11:38:40 +02:00

Source

The #311 cycle-close field test, run source-blind against the built binary. Corpus and full transcript: fieldtests/cycle-311-trace-identity/. Five friction findings, none a defect on its own, all on the path from "a run recorded something" to "I am looking at it". Bundled per the tracker's consolidation rule.

1. The handle listing carries no discriminator

aura chart <render-name> now lists the handles recorded under a name — the cycle's new refusal, and the right shape:

aura: no recorded trace is named `spreadwatch`
  trace handles beginning with `spreadwatch`:
    spreadwatch-74c05cbc
    spreadwatch-7958ba7c
    spreadwatch-f02da484
  pass one of these handles; a single run prints its own as `trace_name` on stdout, …

It answers which handles exist but nothing about which is which. After running one blueprint at three parameterisations, the only public route from a handle back to what that run was is reading runs/traces/<handle>/index.json by hand — the directory listing #309 set out to retire, one level in. The pointer to stdout only helps while that stdout is still on screen, which is exactly not the case when you are asking.

Worth having: a discriminator column (recorded-at, or the manifest keys that differ across the listed handles), or a runs traces verb printing handle plus differing fields.

2. `measure ic` refuses a bare render name blankly, where `chart` lists

The same mistake, two verbs, two answers:

$ aura chart spreadwatch          -> lists the three handles, exit 1
$ aura measure ic graph …         -> "reading run 'graph' traces failed: no recorded run 'graph' under runs/traces", exit 1

measure ic's refusal names neither the <name>-<id8> shape, nor where a handle is printed, nor the one recorded handle that begins with graph and would have answered the call. #309 already established this parity principle by giving measure ic a listing refusal for the family-handle case; the single-run case did not follow.

3. There is no way to ask for a run's identity without running it

"Will this invocation land on top of an earlier one?" is unanswerable in advance, and the closest public answer is awkward to reach:

$ aura graph introspect --identity-id blueprints/1_spread.bp.json
error: unexpected argument 'blueprints/1_spread.bp.json' found     [exit 2]

The working form is --content-id <FILE> --identity-id, which prints both ids even when only the second is wanted. --help documents --content-id [<FILE>] with its file form but --identity-id with none, so the asymmetry is discoverable only from the authoring guide. Giving --identity-id the same [<FILE>] shape would close it.

4. `runs families` and `runs family` are silent on the empty case

After six single runs that all recorded traces:

$ aura runs families                              -> nothing printed, exit 0
$ aura runs family spreadwatch-7958ba7c           -> nothing printed, exit 0   (an argument that cannot name a family)
$ aura reproduce spreadwatch-7958ba7c             -> "no such family '…'", exit 1
$ aura campaign runs                              -> "no campaign runs recorded", exit 0

Both runs verbs succeed silently: the first on a legitimately empty store (single runs form no families — correct, it just never says so), the second on an argument that could never name one. A user hunting for where their runs went asks runs families first and cannot tell an empty store from a broken one. campaign runs already has the empty-state line; reproduce already has the refusal. Orthogonal to #311 and pre-existing.

5. The README's command map omits `chart`

README.md calls itself "a discoverability map of the shipped aura CLI — what commands exist and what they do", and its tables cover exec, graph, runs, reproduce. chart, measure, new, data and nodes are absent, while aura --help lists them all. So the map that claims to enumerate the surface never mentions the verb that reads what a run records; the route from "the run wrote a trace" to "here is how to look at it" runs only through the guide's tap example or --help. Orthogonal to #311 and pre-existing.

Not included here

The field test's remaining findings were routed separately: the node-rename fork is #354, the tap-retraction case went onto #352, and two documentation defects (the guide predicting two directories for a no-op --override, and a C22 clause asserting a convergence the code does not deliver) were fixed inside the #311 cycle.

## Source The #311 cycle-close field test, run source-blind against the built binary. Corpus and full transcript: `fieldtests/cycle-311-trace-identity/`. Five friction findings, none a defect on its own, all on the path from "a run recorded something" to "I am looking at it". Bundled per the tracker's consolidation rule. ## 1. The handle listing carries no discriminator `aura chart <render-name>` now lists the handles recorded under a name — the cycle's new refusal, and the right shape: ``` aura: no recorded trace is named `spreadwatch` trace handles beginning with `spreadwatch`: spreadwatch-74c05cbc spreadwatch-7958ba7c spreadwatch-f02da484 pass one of these handles; a single run prints its own as `trace_name` on stdout, … ``` It answers *which handles exist* but nothing about which is which. After running one blueprint at three parameterisations, the only public route from a handle back to what that run was is reading `runs/traces/<handle>/index.json` by hand — the directory listing #309 set out to retire, one level in. The pointer to stdout only helps while that stdout is still on screen, which is exactly not the case when you are asking. Worth having: a discriminator column (recorded-at, or the manifest keys that differ across the listed handles), or a `runs traces` verb printing handle plus differing fields. ## 2. `measure ic` refuses a bare render name blankly, where `chart` lists The same mistake, two verbs, two answers: ``` $ aura chart spreadwatch -> lists the three handles, exit 1 $ aura measure ic graph … -> "reading run 'graph' traces failed: no recorded run 'graph' under runs/traces", exit 1 ``` `measure ic`'s refusal names neither the `<name>-<id8>` shape, nor where a handle is printed, nor the one recorded handle that begins with `graph` and would have answered the call. #309 already established this parity principle by giving `measure ic` a listing refusal for the family-handle case; the single-run case did not follow. ## 3. There is no way to ask for a run's identity without running it "Will this invocation land on top of an earlier one?" is unanswerable in advance, and the closest public answer is awkward to reach: ``` $ aura graph introspect --identity-id blueprints/1_spread.bp.json error: unexpected argument 'blueprints/1_spread.bp.json' found [exit 2] ``` The working form is `--content-id <FILE> --identity-id`, which prints both ids even when only the second is wanted. `--help` documents `--content-id [<FILE>]` with its file form but `--identity-id` with none, so the asymmetry is discoverable only from the authoring guide. Giving `--identity-id` the same `[<FILE>]` shape would close it. ## 4. `runs families` and `runs family` are silent on the empty case After six single runs that all recorded traces: ``` $ aura runs families -> nothing printed, exit 0 $ aura runs family spreadwatch-7958ba7c -> nothing printed, exit 0 (an argument that cannot name a family) $ aura reproduce spreadwatch-7958ba7c -> "no such family '…'", exit 1 $ aura campaign runs -> "no campaign runs recorded", exit 0 ``` Both `runs` verbs succeed silently: the first on a legitimately empty store (single runs form no families — correct, it just never says so), the second on an argument that could never name one. A user hunting for where their runs went asks `runs families` first and cannot tell an empty store from a broken one. `campaign runs` already has the empty-state line; `reproduce` already has the refusal. Orthogonal to #311 and pre-existing. ## 5. The README's command map omits `chart` `README.md` calls itself "a discoverability map of the shipped `aura` CLI — what commands exist and what they do", and its tables cover `exec`, `graph`, `runs`, `reproduce`. `chart`, `measure`, `new`, `data` and `nodes` are absent, while `aura --help` lists them all. So the map that claims to enumerate the surface never mentions the verb that reads what a run records; the route from "the run wrote a trace" to "here is how to look at it" runs only through the guide's tap example or `--help`. Orthogonal to #311 and pre-existing. ## Not included here The field test's remaining findings were routed separately: the node-rename fork is #354, the tap-retraction case went onto #352, and two documentation defects (the guide predicting two directories for a no-op `--override`, and a C22 clause asserting a convergence the code does not deliver) were fixed inside the #311 cycle.

claude referenced this issue

2026-07-27 15:50:17 +02:00

Is a single run a family of one? The single-run / campaign split costs a classifier, a parser and two sets of guarantees #356

Brummel referenced this issue from a commit

2026-07-27 18:37:38 +02:00

fieldtest: trace-identity cycle — 4 examples, 1 bug / 1 spec-gap / 7 friction / 4 working

Sign in to join this conversation.