# Time-to-Solution — run it live

Three files, no infrastructure. Agents emit events as they work; a stdlib aggregator
rolls them into `metrics.json`; the dashboard renders them.

```
emit.py            # agents call this — one line per action
aggregate.py       # events.jsonl -> metrics.json
events.sample.jsonl# a reconstruction of the QX-250 build (the current baseline)
SPEC.md            # the full design + event schema
```

## 1. At the start of a build (once)
```sh
export TTS_RUN=qx250-2            # a name for this build
export TTS_LOG=/path/events.jsonl # where to append (defaults next to emit.py)
```

## 2. Agents emit as they work — copy-paste
```sh
# a human had to intervene  (kind = prompt | unblock | approve)
python emit.py human_touch --kind prompt          # ← one per user turn / direction
python emit.py human_touch --kind unblock         # you fixed something the agent couldn't
python emit.py human_touch --kind approve         # a gate sign-off (the only kind that should survive)

# a unit of agent work finished
python emit.py work_completed --domain fpga --tool Questa --deliverable gateware \
       --duration_s 900 --iterations 2 --result pass

# a tool-to-tool handoff (the seam tax)
python emit.py seam_crossing --domain electrical --tool bridge \
       --from neutral-bundle --to Capital --duration_s 1200 --failures 5

# a downstream step invalidated an upstream artifact
python emit.py rework --deliverable compute.html --cause "false claim: FPGA is a device in Capital"

# a criterion was checked
python emit.py verification --domain fpga --deliverable safety \
       --method formal --machine_checkable true --result pass
```
Any `--key` you don't see above lands in `meta` automatically — the schema is open.

## 3. Compute the dashboard
```sh
python aggregate.py "$TTS_LOG" metrics.json
```
Then the dashboard reads `metrics.json`. Compare run-to-run: did time-to-solution fall,
did **prompts-per-deliverable** drop, did **verification coverage** rise? That comparison is
the whole point.

## The one habit that matters
Emit **`human_touch --kind prompt` once per turn.** That single line, across a build, is the
autonomy number — the thing the agentic program layer exists to drive to zero. Everything else
is gravy; start there.