Adom Fields

@@ -1,51 +0,0 @@-----name: aiflow-measurement-description: How an adom-aiflow run is measured, in John's words (2026-09-14). The number is the wall clock from the human's first prompt to the AI saying "done, here is your video", and the per-step cost is the AI's thinking, not the binary's seconds. Every command is a turn in run.jsonl with the thinking gap before it in an append-only run.jsonl; every return to an earlier step (placement moved because a pour had bad heatsinking) is recorded with its reason. Read this before you start, run, report, or compare a aiflow run, and before you hand a run to another engine. Trigger words: aiflow stats, measure the run, how long did each step take, prompt to done, AI thinking time, iterative rework, go back to placement, fable vs codex comparison, deliver the video, run.json ledger.------# Measuring a aiflow run--What is being measured is the AI. Deterministic code is fast; the AI thinking its way through the board, the placement, the routing, the pours, the current and thermal work is slow, and that is the cost the chart has to show. Reporting the binary's stage seconds ("route 25 s", "capture open 51 s") while the human sat watching the AI think for twenty minutes is wrong: it took twenty minutes.--## The clock--- Starts at the human's first prompt that starts the aiflow. Pass it exactly: `start --prompt-time <UTC of that message>`.-- Stops when the AI says "I'm 100 % done. Here is your video. Check it out." That moment is `deliver --video <mp4> --message "<what you said>"`. `finish` (the qualified board) is a milestone inside the run, not the end of it.-- Nothing inside is excluded. Waiting for the human, an overnight gap, a re-take: all of it counts. If a gap should be explained, explain it in a marker; do not subtract it.--## The ledger (run.jsonl, append-only)--- `run.jsonl` is the record: one JSON line per event, appended, never rewritten (a crash or a rewrite cannot lose a turn). Events: `start`, `turn` (a command begins), `turn-end`, `step` (a visit, with `back` and `why`), `stage-start`/`stage-end` (the binary's own work), `outcome`, `marker`, `clip-start`/`clip-stop` (one clip per step), `artifact` (what a step made: the clip and its seconds, the 10x cut, the zone state, the plans), `finish`, `deliver`. The final video is composed from the artifacts (docs/video.md). `run.json` is the derived state and summary; when they disagree, the ledger wins. `adom-aiflow ledger` prints it in order with the per-step table; `--json` streams the lines.-- `turn`: every command the AI runs is a turn: the step it belongs to, the command, when it began, `thinkingSeconds` (the gap since the previous turn ended, or since the prompt for the first one: the AI's thinking that led to this command), `binarySeconds` (the tool's own time), and the first line it answered. The binary writes this itself; nothing to remember.-- `steps`: the AI declares what it is working on with `step <name>` (intake, placement, routing, pours, current, thermal, capture, finish, or its own name). Every command until the next `step` is charged to it. A return to an earlier step is `step <name> --back --why "<what sent you back>"`; the reason is part of the record.-- `summary.steps` at `finish` and `deliver`: per step, wall = thinking + tool, turns, visits, returns, longest single think. The sum over steps is the whole run. `promptToDeliveredMinutes` is the headline number; `promptToFinishMinutes` is the milestone.--## Iteration is expected--The AI can do a fine placement early and only find out at the pours that a low-side tab has no room for copper, or at the thermal step that a heat spreader fills as islands under dense routing. Then it goes back: moves parts, moves vias, reroutes, pours again, analyzes again. That is the same iterative analysis a human does, and every return is a visit with a reason in the ledger. Do not hide rework by editing the spec quietly: declare the step, say why, do the work, come forward again.--## Evidence the human will check--The final video and the page are the evidence that the run is any good. They have to show, per step, the real length of time (the AI's), and the substance: the copper pour current analysis, the heat analysis, the copper kept for ablation, and what was refused and why. A video that shows a 51-second stage the human waited twenty minutes for is not evidence.--## Before a comparison--Get it right with one engine first, on a fresh prompt, from `start` to `deliver`, and read the ledger back: does every step carry its thinking time, do the returns say why, does the video match the ledger. Only then hand the same board, spec, flow and prompt to the other engine, so both runs measure the same thing.--## Honesty--- A run that was assembled from earlier work with a back-dated prompt is a proving run of the tool, not a measured run of the AI. Say so.-- If you have not run the flow end to end from a prompt, the answer to "how long did it take you" is "I have not run it yet; I have to attempt it for the first time to answer."---## Plan usage, the second cost line--Neither engine can see its own token bill reliably, so the binary reads what the provider shows the human: the percent used of every plan limit (Claude: the 5-hour window, the week, and each model-scoped weekly limit such as Fable; Codex: its primary and secondary rate-limit windows), from the Claude Code and Codex sign-ins in the container, with the same calls the Hydrogen usage widgets make. It snapshots at `start`, at every `step`, at `finish` and at `deliver` (`adom-aiflow usage` any time), writes each snapshot to run.jsonl, and the summary and the run page show "Fable 13 % to 16 %" per limit. That is the cost line to compare when tokens and dollars are nulls. Footnote it every time: the limits are per account, so other AI threads signed in as the same user move the same numbers; the delta is an upper bound unless the run was the only thread active.--## Cost, two ways--Each engine writes its token counts and the dollar figure at API rates into run.json (`tokens.in`, `tokens.out`, `usd.api`). The chart shows that figure, which is what commercial users on API plans pay, and beside it the same figure divided by 20 (`usd.plan20x`), which is the real cost on a 20x subscription plan. Both lines, always; neither alone tells the story.--## Sessions (2026-09-15)--The clock of record is AI time, not wall time: the sum of the run's sessions (a human prompt to the AI's done) with idle gaps over 15 min cut out. Mark follow-up prompts with `prompt --text` and answers with `done --message`; `deliver` closes the first task. The benchmark is the AI time from the first prompt to `deliver`. docs/time.md on the page has the rules.