@bglocation/tune-context 2.3.1 → 2.5.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "tune-context",
       "source": "./",
       "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-      "version": "2.3.1",
+      "version": "2.5.0",
       "author": {
         "name": "Szymon Walczak",
         "url": "https://bglocation.dev"

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "tune-context",
   "displayName": "tune-context",
   "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-  "version": "2.3.1",
+  "version": "2.5.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,197 @@ All notable changes to `@bglocation/tune-context` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0] — 2026-09-03
+
+### Fixed
+
+- **`prompt-metrics` charged 45% of all cache-read tokens twice** (found while
+  reviewing TASK-089). A transcript repeats entries verbatim: 11 296 of 36 463
+  local entries (31%) carry a `uuid` already written *earlier in the same file*,
+  6 739 of them assistant turns with a `usage` block, the copies differing only
+  in a cosmetic `slug`. The collector summed both. Local run total drops from
+  $4 566 to $2 323 — an inflation of **1.97×**, several times the effect
+  EPIC-009 is trying to measure. Repeats are now skipped (scoped to one file:
+  zero `uuid`s are shared between files) and counted on stderr, so the drop
+  explains itself rather than looking like a different tool.
+  **Every cost figure this project produced before 2026-08-02 is too high**;
+  `COST_EVALUATION_PROCEDURE.md` §11a carries the correction, including the
+  delegation baseline, which moves from ~0.7 to ~0.3 per session. The frozen
+  §10 thresholds are deliberately left alone — the correction makes the
+  delegation gate stricter relative to the norm, and refitting a threshold to
+  new data is the thing that section forbids.
+
+- **`prompt-metrics` billed one API response as many** (TASK-092, reported by a
+  Claude Code session working in a different project). One response reaches the
+  transcript as *several* entries — one per content block: thinking, text, each
+  `tool_use` — every one with its own `uuid` but carrying an **identical copy of
+  the same `usage` block**. The `uuid` dedup above cannot see this class by
+  construction: those uuids differ by design. Over 19 transcripts, 11 295
+  entries for 5 954 responses. `usage` is now keyed to the RESPONSE
+  (`message.id`, falling back to `requestId`) and the extra entries are counted
+  on stderr. On the same frozen transcripts the run total drops **$1 372.69 →
+  $679.35 (2.02×)**, on top of the 1.97× above.
+  The inflation is **not flat** across token classes (cache-read 1.82×, output
+  2.17×, cache-write 2.39×, input 2.45×) and does **not** cancel in a ratio of
+  two arms: the factor *is* the number of content blocks per turn — how many
+  tools the model reached for, which is the variable the doctrine sets out to
+  move. Per-session spread 1.66×–2.24×.
+  The guard sits **after** the `tool_use` loop, because those blocks are *not*
+  duplicated (6 403 blocks, 6 403 distinct ids): skipping whole entries would
+  have dropped ~2/3 of every tool call and gutted the adoption half of the
+  analysis. All three turn counters are guarded — `api_turns`, `sidechain_turns`
+  and the unattributed bucket — and an entry with neither `message.id` nor
+  `requestId` is **billed** and reported, never assumed unique.
+  **Every cost figure this project produced before 2026-09-03 is too high
+  again**, including the frozen EPIC-009 rows under `docs/` and the TASK-090
+  verdict computed from them. The skew correlates with the arm, so that verdict
+  rests on numbers that have to be recomputed before it means anything.
+
+- **The unattributed bucket dropped tool calls and server-tool cost**
+  (TASK-093). An entry whose `parentUuid` chain does not resolve never reaches
+  the row path, so its `tool_use` blocks reached no counter at all, and its
+  `usage.server_tool_use` was dropped by `addUsage()`, which copies token fields
+  only. The two are different in kind: the tool calls are an **adoption**
+  denominator, not money — a tool call is paid for in tokens, and those were
+  always billed here — while web search is billed **per request** ($10/1000), so
+  counting the entry's tokens does not cover it. Measured: 1 tool call in 66 765
+  entries, and **0** web searches in the whole local corpus, on 30 061 entries
+  that carry a `server_tool_use` block — the cost hole is dormant, not closed.
+  The bucket now carries `tool_calls`, `agent_spawns`, `web_search_requests` and
+  `web_fetch_requests`, printed on stderr only when non-zero, and an
+  unattributed subagent spawn is named as UNCAPTURED cost (class 3) rather than
+  going missing from the one counter that sizes that blind spot. `server_tool_use`
+  is counted once per response (it rides inside `usage`, so it *is* duplicated);
+  the `tool_use` blocks are counted per entry (they are not). Reconciled against
+  an independent counter over three populations: tool calls now agree **to the
+  unit** (6 403 / 99 / 18) without the manual correction the TASK-092 review
+  still needed.
+
+### Added
+
+- **`eval/report.mjs` — the measurement as one self-contained HTML file**
+  (TASK-091, EPIC-009). `node eval/report.mjs --aggregate aggregate.json --out
+  report.html`: data embedded as JSON, charts as inline SVG, **no network and no
+  build step** — it opens from `file://` on a machine with no internet, which is
+  where it will actually be read. The failure it is built against is not a wrong
+  number but a right number about the wrong thing: a chart persuades harder than
+  the caveat under it, so **when a TASK-090 gate holds the arm-comparison chart
+  is not drawn at all** — not greyed out, not captioned. The per-pair costs stay
+  in a table, because those are what a repeat run is planned from. The order
+  effect is printed the same size and in the same place as the arm effect (§11b),
+  a token count never appears without its five classes, the two pools are
+  rendered by two calls that share no accumulator, and the honesty counters —
+  rejected rows with reasons, sessions dropped for switching arm, the delegation
+  cost that is a floor rather than a total — are a section rather than a footer.
+  Visuals follow the `dataviz` skill: palette validated in light and dark,
+  zero-baseline axes, hairline chrome. 22 tests, one group per acceptance
+  criterion, and the load-bearing one asserts the **absence** of a chart.
+
+- **`eval/analyze.mjs` — the aggregate per arm** (TASK-089, EPIC-009). Rows are
+  data; this is the step between them and the sentence "that arm cost less" —
+  and it deliberately stops before the sentence, because the thresholds that
+  would justify it are frozen by the PO in TASK-090. The paired measurement
+  (branch `exp/<task>/<arm>`) and ordinary work (attributed by the TASK-087
+  ledger) come out as two objects with **different shapes** and no total above
+  them, so the two populations cannot be added by accident. Per arm: prompts,
+  sessions, pairs, cost as median **and** spread (a single mean hides the one
+  prompt that read 200 k tokens), `work_s` rather than time-since-submission,
+  tokens always in five classes, tools, delegations, model/effort distribution,
+  and `pass_order` per pair so the order effect can be subtracted from the arm
+  effect (§11b).
+- **Discarding is output, not silence.** Every row lands in an arm or in a named
+  counter, and `rows_in = rows_used + rows_rejected` is asserted by a test. A
+  session whose rows disagree about the arm is dropped **whole** (the arm is a
+  property of the session: `settings.json` and MCP load at startup), a branch
+  that mimics the convention without matching it goes to a counter rather than
+  to the nearest plausible arm, and an unpriced row leaves the cost but stays in
+  the sample.
+- **Subagent cost is now measured from below** (TASK-089 criterion 8). The
+  result of an `Agent` call carries its own `usage` and `resolvedModel`, so each
+  delegation is priced with the existing table and rides on the row as
+  `delegations[]` — deduplicated by `agentId`, because the identical entry is
+  written to several transcript files and without that the figure comes out 2×.
+  It is a **lower bound** and is never added to the parent session's cost; the
+  spawns that left no priced result are counted beside it, since that part is
+  cost we have no figure for at all.
+
+## [2.4.0] — 2026-07-31
+
+### Added
+
+- **`tune-context experiment` — the second arm** (TASK-087, EPIC-009). Measuring
+  one arm is not measuring: until now there was no way to run the same work
+  *without* the doctrine and without RAG, so every figure the reports produced
+  was absolute and had nothing to be compared against. `experiment set --tc off
+  --rag off` switches off hook registrations, the managed `CLAUDE.md` block, the
+  doctrine skills and the agents (the full arm, PO decision) plus the project
+  `.mcp.json`; `restore` puts every byte back. Each `set` appends to an
+  append-only ledger (`<config dir>/tune-context/experiment.jsonl`) — the source
+  of truth an analyzer uses to assign a session to an arm.
+- **`restore` refuses rather than clobbers.** Every touched path is fingerprinted
+  and copied aside *before* it is modified — so a `set` interrupted halfway is
+  still reversible — and `restore` compares each path against what `set` left
+  there. A file edited during the arm (a permission added to `settings.json`,
+  text written below the `CLAUDE.md` marker — the TASK-082 scenario) aborts the
+  whole restore and reports **what** diverged, not just which file: the first
+  differing line with a preview of both sides for a text file, per-file counts
+  and names for a directory, plus the path to the saved copy. Refusal is the
+  correct outcome here, not a failure.
+- **`verify` understands the off arm.** With an arm set it reports "off" instead
+  of a broken install — and stays RED when the arm did *not* fully land, e.g. a
+  leftover hook registration still firing. Reporting a correctly disabled
+  doctrine as breakage would be the EPIC-006 false-red regression pointing the
+  other way. `init` now refuses to run while an arm is set: it would re-install
+  what the arm parked and leave `restore` with fingerprints it never wrote.
+
+- **Rows say which arm they belong to** (TASK-088, EPIC-009). `prompt-metrics`
+  rows from a branch shaped `exp/<task>/<arm>` now carry `exp_task`, `exp_arm`,
+  `exp_arm_source`, `exp_ledger_arm` and `pass_order`. The branch says which arm
+  was *intended*, the ledger which was *set* — and when they disagree the tool
+  does **not** pick a winner: the arm is left unresolved with the reason on the
+  row (`conflict:ledger`, `conflict:no-ledger-entry`, `conflict:branch-changed`),
+  because silently assigning a run to an arm is exactly the false saving the
+  paired measurement exists to prevent. The branch parser is strict for the same
+  reason: `exp/task-089/off-by-one` and `feat/exp/task-089/on` resolve to nothing
+  rather than to the nearest matching arm.
+- **`pass_order` on the row.** The second implementation of the same task is
+  cheaper for a reason that has nothing to do with the arm — the solution is
+  already known — and that effect runs in the same direction as the one being
+  measured. Recorded per (task, arm) from the start time, it is what lets the
+  order effect be subtracted from the arm effect instead of being counted as one.
+
+- **`restore` ends a measurement run even when it moved nothing.** The switch
+  only ever turns things *off*, so the `on` arm parks no files — and `restore`
+  used to refuse there, ledger entry included. That left the `on` arm's window
+  open forever: a follow-up a week later, in the same worktree on the same
+  `exp/` branch, still resolved to `branch+ledger` and joined the sample, while
+  the identical work after an `off` arm was flagged and excluded. A leak on one
+  side only is worse than a leak on both, because the two sides are what the
+  epic compares. Now `restore` closes the ledger window whether or not it had
+  bytes to put back, and refuses only when there is no open arm to close.
+
+### Fixed
+
+- **A cost that is not a number is no longer counted as a cost.** `NaN` is
+  neither `null` nor `undefined`, so a row carrying one passed every "is there a
+  price here?" check, entered the priced count, and turned the whole run's total
+  into `$NaN` — every other row's money gone while the counter still claimed to
+  have priced them. The published amount is now refused unless it is finite, and
+  the roll-up checks each class, not only the total. The way in is closed too:
+  the price, tier and geo tables are looked up by *own* key, so a `service_tier`
+  spelled `constructor` reads as unknown instead of handing back a function from
+  `Object.prototype`.
+
+### Notes
+
+- `rag off` covers the **project** `.mcp.json` only. `~/.claude.json` is rewritten
+  by Claude Code while it runs, so the switch never touches the user scope —
+  `experiment status` says this explicitly instead of implying RAG is globally
+  off.
+- The arm belongs to the **session**: `settings.json` and MCP servers load at
+  startup, so a `set` applies from the next Claude Code start. Both `set` and
+  `status` say so; nothing here restarts anything for you.
+
 ## [2.3.1] — 2026-07-28
 
 ### Fixed
@@ -464,6 +655,8 @@ action needed on upgrade.
   (`explore-cheap`, `reviewer`), the PreCompact / SessionStart / PostToolUse hook
   suite, and the adoption report (`eval/adoption-report.mjs`).
 
+[2.5.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.5.0
+[2.4.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.4.0
 [2.3.1]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.1
 [2.3.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.3.0
 [2.2.0]: https://gitlab.com/bglocation/tune-context/-/tags/v2.2.0

package/README.md

@@ -17,7 +17,7 @@ tune-context/
 ├── agents/            # explore-cheap, reviewer (model right-sizing)
 ├── hooks/             # PreCompact state-doc, SessionStart re-inject, adoption log, context reminder + hooks.json
 ├── bin/ + cli/        # `tune-context init` — deterministic detect → generate → verify
-├── eval/              # adoption-report.mjs (the rag-usage analog)
+├── eval/              # adoption-report.mjs (the rag-usage analog), prompt-metrics.mjs, pricing.mjs, arm.mjs, analyze.mjs, verdict.mjs, report.mjs
 └── scripts/           # verify-pack, smoke-init, sync-tune-context (dev/maintenance)
 ```
 
@@ -332,19 +332,201 @@ instead of printing a number the doubling would have faked.
 `~/.claude/tune-context/` (or the `CLAUDE_CONFIG_DIR` override) and records only
 tool names, file paths, and skill/agent names — never full Bash command strings.
 
-**Honest scope:** this is a *behavioral proxy*, not a bill. Token cost lands only
-in OTEL (`CLAUDE_CODE_ENABLE_TELEMETRY=1` → `claude_code.cost.usage`, needs a
-collector), never a hook; and caveman is an output style with no tool call, so it
+**Honest scope:** this is a *behavioral proxy*, not a bill. The hook log carries
+no tokens, so dollars come from `prompt-metrics` below (or from OTEL, which is
+Anthropic's own figure); and caveman is an output style with no tool call, so it
 can't be counted this way. Doctrine applied as *method* — narrow reads,
 contracts-first edits, delegation — is only partly visible too: no `Skill` call,
 but its trace shows up in the report's edit:read ratio, so the verdict never
 reads zero `Skill` calls as "unused."
 
+### Per-prompt metrics from transcripts (`eval/prompt-metrics.mjs`)
+
+The adoption report reads *our* hook log. `prompt-metrics` reads the transcripts
+**Claude Code writes itself** (`<config dir>/projects/<slug>/<session>.jsonl`) and
+emits one JSONL row per prompt — time, tokens split by cache class, model,
+effort, tools, delegations, and cost in dollars (`eval/pricing.mjs`):
+
+```bash
+node eval/prompt-metrics.mjs                              # every transcript
+node eval/prompt-metrics.mjs --transcript <path.jsonl>    # one session
+node eval/prompt-metrics.mjs --dir <dir> > prompts.jsonl  # JSONL on stdout
+```
+
+Rows go to stdout, a run summary to stderr — so a pipe stays clean. Two things
+that source makes possible and a hook cannot: it works for **past** sessions, and
+it works when tune-context is switched **off** (a disabled hook records nothing,
+and that is exactly the arm a comparison needs).
+
+Honest scope, printed on every run:
+
+- **`list_cost_usd` is API list price, not your bill.** A Pro/Max subscription
+  charges a flat fee and consumes plan limits; nothing here is billed per token.
+  The figure answers *"what would this work have cost through the API"* — which
+  is the right yardstick for comparing two arms, and the wrong number to
+  reconcile against a statement. The field is named so the qualifier travels
+  with the data.
+- **Repeated entries are skipped, and that changed every figure.** A transcript
+  writes some entries twice — 11 296 of 36 463 local ones (31%) repeat a `uuid`
+  already written *in the same file*, 6 739 of them assistant turns with a
+  `usage` block, the copies identical apart from a cosmetic `slug`. Summing both
+  charged 45% of all cache-read tokens twice: run totals from before 2026-08-02
+  are inflated ~1.97×. The skip is scoped to one file (no `uuid` is shared
+  between files) and the count is printed on every run.
+- **Cache-aware, because a naive token sum is off by ~10×.** Cache reads cost
+  0.1× and writes 1.25×/2×; the local run carries 4.18 **billion** cache-read
+  tokens against 521 k plain input ones — 99.9% of the figure is cache and
+  output. The total never appears without its per-class split, and a model the
+  table doesn't know yields `null` plus an `UNPRICED` count, never a zero.
+- **Prices are data, dated, and expire.** `eval/pricing.mjs` holds one table
+  taken from the published pricing page with its retrieval date, storing base
+  input/output only and deriving the three cache columns from the documented
+  1.25×/2×/0.1× multipliers — a test asserts the derivation reproduces every
+  published row. Service tier (batch −50%), fast mode, and `inference_geo`
+  (us +10%) are applied; the claude-sonnet-5 introductory price ends in the
+  table on 2026-08-31. Rows are priced at the **prompt's own timestamp**, so
+  re-running the report later yields the same figure.
+- **Subagent cost is measured from below, not captured.** Subagent turns never
+  reach the parent transcript (zero sidechain entries over 34 local ones), but
+  the **result** of an `Agent` call carries its own `usage` and `resolvedModel`
+  — so each delegation is priced with the same table and rides on the row as
+  `delegations[]`, deduplicated by `agentId` because the entry is written twice.
+  That figure is a **lower bound**
+  (`cache_read` grows linearly with the subagent's tool calls, which looks like
+  its last turn rather than a sum) and is **never added** to the row's own cost.
+  `agent_spawns` is still counted next to it: the spawns that left no priced
+  result are cost there is no figure for at all.
+- **Queue wait is not work.** `queued_s` (submission → first assistant entry) is
+  reported apart from `work_s`, because a prompt sent while the agent is busy
+  waits in a queue and that is the user's time. `max_gap_s` exposes the same
+  thing *inside* a turn — a tool call blocked on a permission prompt lands in
+  `work_s` otherwise.
+- **Model and effort change mid-session** (measured), so both ride on every row,
+  with a per-model token split when a single prompt used more than one.
+- Entries that can't be attributed to a prompt are **counted and reported**,
+  never silently dropped. Same for the two ways the figure can be too low:
+  `usage.iterations` reporting more than the `usage` we price from (3 turns
+  locally), and web searches, which are billed per request ($10/1000) rather
+  than per token and so sit outside the token total. Web *fetch* is free.
+
+### The other arm (`tune-context experiment`)
+
+A cost figure with nothing to compare it against is a number, not a measurement.
+This switch turns the doctrine **off** so the same work can be run twice —
+`tc={on,off}` × `rag={on,off}` — and records which arm was in force when:
+
+```bash
+tune-context experiment status                              # what is set, and what the config actually shows
+tune-context experiment set --tc off --rag off --note "pair 1"
+tune-context experiment restore                             # byte for byte, or a refusal
+```
+
+- **`tc off` is the full arm** (PO decision, EPIC-009): hook registrations in
+  `settings.json`, the managed block in the project `CLAUDE.md`, the doctrine
+  skills, the agents. Four interventions in one variable on purpose — at small
+  *n* the biggest effect is the easiest to detect; splitting them is the *next*
+  experiment.
+- **`rag off` means this project's `.mcp.json`, and nothing else.** The user
+  scope (`~/.claude.json`) is rewritten by Claude Code while it runs, so the
+  switch never touches it — `status` says so out loud instead of letting you
+  assume RAG is off globally. Check `claude mcp list` before a measured run.
+- **Reversibility comes before the change.** Every touched path is fingerprinted
+  and copied aside *before* it is modified, so a `set` that dies halfway is still
+  undoable. `restore` compares each path against what `set` left there and
+  **refuses** if anything changed in between, naming the file *and the
+  difference* (first differing line for a text file, changed/added/removed files
+  for a directory, and where the saved copy is) — the working session between the
+  two commands is exactly when you might add a permission or write below the
+  `CLAUDE.md` marker, and silently erasing that is worse than refusing.
+- **The ledger is the source of truth**
+  (`<config dir>/tune-context/experiment.jsonl`, append-only). An analyzer
+  assigns a session to an arm by timestamp; detecting the arm from a transcript
+  is a cross-check, never the verdict. Every `set` appends — including one that
+  changes nothing, because a run whose ledger is silent at its start cannot be
+  assigned to an arm at all.
+- **The arm belongs to the session.** `settings.json` and MCP servers are read at
+  startup, so it applies from the next Claude Code start; flipping it mid-session
+  produces a mixed session, which the analysis throws away.
+- `tune-context verify` reads the arm and reports **"off"** rather than a broken
+  install — and stays RED if the arm did not fully land. `init` refuses to run
+  while an arm is set: it would re-install what the arm parked and leave
+  `restore` with nothing it recognises.
+
+The measurement protocol that uses this — paired runs on `exp/<task>/<arm>`
+branches, frozen prompt script, verdict gates — is
+[COST_EVALUATION_PROCEDURE.md](COST_EVALUATION_PROCEDURE.md).
+
+### Per-arm aggregate (`eval/analyze.mjs`)
+
+Rows are data, not an answer. `analyze` turns a stream of them into one
+aggregate per arm — and stops one step short of ruling which arm won, because
+the thresholds that would do the ruling are frozen by the PO, not by the model:
+
+```bash
+node eval/prompt-metrics.mjs > rows.jsonl
+node eval/analyze.mjs --rows rows.jsonl > aggregate.json   # summary on stderr
+```
+
+- **Two populations, never one number.** The paired measurement (branch
+  `exp/<task>/<arm>`, everything else held constant) and ordinary daily work
+  (attributed by the ledger, nothing held constant) come out as two separate
+  objects with different shapes. There is no total above them and no list of
+  pools to fold over — adding them has to be written out by hand and meant.
+- **Discards are the output too.** Every row lands either in an arm or in a
+  named counter, and `rows_in = rows_used + rows_rejected` is asserted by a
+  test. A session whose rows disagree about the arm is dropped **whole** —
+  `settings.json` and MCP servers load at startup, so a session that switched
+  arms was never in one — and a branch that *mimics* `exp/<task>/<arm>` without
+  matching it (`exp/task-089`, `exp/`) goes to a counter, never to the nearest
+  plausible arm.
+- **Median and spread, not the mean alone.** One 44-hour turn or one prompt that
+  read a 200 k-token file moves a mean of six and leaves the median untouched;
+  the gap between the two is itself the finding, so both are reported with
+  p25/p75, IQR and the extremes.
+- **An unpriced row leaves the cost, not the sample.** It stays in `n_prompts`,
+  sits outside the total, and the pool says `cost_complete: false` with the
+  model that caused it named.
+- **`pass_order` per pair.** The second implementation of a task is cheaper for
+  a reason that has nothing to do with the arm, and it pushes the same way as
+  the effect being looked for. The per-pair, per-arm cost is carried so the two
+  can be separated arithmetically (procedure §11b).
+
+### The report (`eval/report.mjs`)
+
+One HTML file — data embedded as JSON, charts as inline SVG, no network and no
+build step, so it opens from `file://` on a machine with nothing installed:
+
+```bash
+node eval/analyze.mjs --rows rows.jsonl > aggregate.json
+node eval/report.mjs --aggregate aggregate.json --out report.html
+node eval/report.mjs --aggregate aggregate.json --rejected-runs journal.json --out report.html
+```
+
+`--rejected-runs` carries what the run journal recorded as §7 invalidations
+(`[{ session, task, arm, prompts, reason }]`). **Omitting it is not the same as
+passing `[]`**: the first says nobody asked the journal, and the verdict is held
+for exactly that reason — a rejection share whose denominator is unknown is a
+quietly dropped sample wearing a passing gate.
+
+- **A withheld verdict is the page, not a footnote.** When a gate holds, the
+  arm-comparison chart is *not drawn at all* — not greyed out, not captioned. Two
+  bars side by side assert "this is a comparison" more loudly than any caption
+  can withdraw it. The per-pair costs stay in a table: those are what a repeat
+  run is planned from.
+- **The order effect is printed the same size as the arm effect.** A page that
+  shows one large and the other in small print has already made the claim §11b
+  refuses.
+- **Tokens never appear without their five classes**, the two pools are never
+  added, and the honesty counters — rejected rows and why, sessions dropped for
+  switching arm mid-flight, the delegation cost that is a floor and not a total —
+  are a section of their own rather than a footer.
+
 ### Getting real cost (OTEL) — outside tune-context
 
 tune-context does not set this up for you (deliberate — see TASK-062: it needs
-infra this tool stays zero-infra without). If you want actual dollars instead of
-the behavioral proxy above:
+infra this tool stays zero-infra without). `prompt-metrics` above computes cost
+from a public price list, which is an *independent* calculation, not Anthropic's
+invoice — OTEL is the way to check it against the real one:
 
 ```bash
 export CLAUDE_CODE_ENABLE_TELEMETRY=1     # off by default