@bglocation/tune-context 2.5.0 → 3.0.0

package/eval/verdict.mjs

@@ -1,8 +1,12 @@
+#!/usr/bin/env node
 // verdict — the step analyze.mjs deliberately stops before: may this run say
 // "one arm is cheaper"? See tasks/TASK-090.
 //
-// Pure predicates over the TASK-089 aggregate. No disk, no clock, no stdout, no
-// formatting — an aggregate in, a decision out. TASK-091 renders it.
+// Pure predicates over the TASK-089 aggregate. No disk, no clock, no stdout —
+// an aggregate in, a decision out. TASK-091 renders it as HTML; formatVerdict()
+// renders it as text for a terminal. The CLI section at the bottom of this file
+// (TASK-096) is the ONLY place in it that reads a file, stdin or the process,
+// or writes anything: everything above it stays a function of its arguments.
 //
 // The failure this file exists to prevent is not a wrong number; it is a right
 // number about the wrong thing. An aggregate that adds up perfectly still
@@ -35,20 +39,43 @@
 // constant — it is background for asking whether the paired result points the
 // same way, and it is never evidence (analyze.mjs keeps the two un-addable by
 // shape; this file simply never reaches for the second one).
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { endQuietlyOnClosedPipe, isEntryPoint, readStdin } from '../cli/entry-point.mjs';
+import { meterStamp, stampProblem } from '../cli/version.mjs';
 import { ARMS } from './analyze.mjs';
 import { formatUsd } from './pricing.mjs';
 
 /**
- * Frozen with the PO on 2026-07-30 (COST_EVALUATION_PROCEDURE §10, §11).
+ * An input this module refuses: an aggregate that is not one, a run journal of
+ * the wrong shape, and — in the CLI — a file that is missing or is not JSON.
+ * One class for all of them, so a CLI can answer exactly these with a message
+ * and exit 1, and let anything else go up as the bug it is.
+ *
+ * A TypeError, because the pure functions threw TypeError at this boundary
+ * before the class existed, and a caller matching on that keeps working.
+ */
+export class VerdictInputError extends TypeError {
+  constructor(message) {
+    super(message);
+    this.name = 'VerdictInputError';
+  }
+}
+
+/**
+ * Frozen with the PO on 2026-07-30 (COST_EVALUATION_PROCEDURE §10, §11); the
+ * seventh gate, meter_mixed, frozen by the PO on 2026-10-15 (EPIC-010).
  *
  * Each entry carries its own `frozen` date next to its value, not just the
  * table: a later change to one threshold must be visible as a change to THAT
  * line. A threshold moved after seeing the data is a threshold fitted to the
  * result — if it has to happen, it lands in `amended` with a new date and the
- * admission that it happened after the run.
+ * admission that it happened after the run. A gate ADDED before the next run is
+ * not that, which is why meter_mixed carries its own date and `amended` stays
+ * empty; the top-level `frozen` stays the date the table was first frozen.
  */
 export const VERDICT_THRESHOLDS = {
-  schema: 'tune-context/verdict-thresholds@1',
+  schema: 'tune-context/verdict-thresholds@2',
   frozen: '2026-07-30',
   frozen_by: 'PO',
   source: 'COST_EVALUATION_PROCEDURE.md §10 and §11 (tasks/TASK-090)',
@@ -107,6 +134,17 @@ export const VERDICT_THRESHOLDS = {
         ' rejected run exceeds it. That is the point of the threshold, not a flaw in it: at four sessions there is' +
         ' nothing to spare. A broken run is repeated (§7), not absorbed.',
     },
+    meter_mixed: {
+      requires: 'single identifiable stamp across the chain',
+      frozen: '2026-10-15',
+      note:
+        'Chosen by the PO (EPIC-010 decision 2), not by the model — the TASK-062 anti-bias rule. The meter is the whole' +
+        ' chain: rows (prompt-metrics), the aggregate (analyze) and this verdict each carry the stamp of the code that' +
+        ' computed them, and in the EPIC-009 series the measured tasks changed analyze and verdict themselves. So' +
+        ' exactly one stamp, and one that names code: `.dirty` was computed from uncommitted changes and `+unknown`' +
+        ' from a checkout git could not read — neither can be rebuilt, so neither can be checked. EPIC-009 was voided' +
+        ' because its rows came from a meter nobody could name.',
+    },
   },
 };
 
@@ -136,28 +174,34 @@ export const VERDICT_THRESHOLDS = {
  */
 function normalizeJournalRejects(input) {
   if (input === undefined || input === null) return { reported: false, rows: 0, runs: [] };
-  if (!Array.isArray(input)) {
-    throw new TypeError('verdict: rejectedRuns must be an array of journal entries, or omitted to say nobody asked');
-  }
-  const runs = input.map((run, i) => {
-    const prompts = run?.prompts;
-    if (!Number.isInteger(prompts) || prompts < 0) {
-      throw new TypeError(
-        `verdict: rejectedRuns[${i}].prompts must be a non-negative integer — this gate counts rows, and a` +
-          ' rejected run whose prompt count is a guess cannot be counted into a threshold',
-      );
-    }
-    return {
-      session: run.session ?? null,
-      task: run.task ?? null,
-      arm: run.arm ?? null,
-      prompts,
-      reason: run.reason ?? null,
-    };
-  });
+  const problem = journalShapeProblem(input);
+  if (problem !== null) throw new VerdictInputError(`verdict: ${problem}`);
+  const runs = input.map((run) => ({
+    session: run.session ?? null,
+    task: run.task ?? null,
+    arm: run.arm ?? null,
+    prompts: run.prompts,
+    reason: run.reason ?? null,
+  }));
   return { reported: true, rows: runs.reduce((n, r) => n + r.prompts, 0), runs };
 }
 
+/**
+ * What is wrong with a supplied journal, or null when nothing is. A message
+ * rather than a throw, because two layers report it in their own words — the
+ * pure function above, and the CLI reading a `--rejected-runs` file — and the
+ * check itself must exist once.
+ */
+function journalShapeProblem(input) {
+  if (!Array.isArray(input)) return 'rejectedRuns must be an array of journal entries, or omitted to say nobody asked';
+  const i = input.findIndex((run) => !Number.isInteger(run?.prompts) || run.prompts < 0);
+  if (i === -1) return null;
+  return (
+    `rejectedRuns[${i}].prompts must be a non-negative integer — this gate counts rows, and a` +
+    ' rejected run whose prompt count is a guess cannot be counted into a threshold'
+  );
+}
+
 /**
  * Reject reasons that mean "a run that was TRYING to be part of the paired
  * measurement failed" — the §7 invalidations, counted in rows because that is
@@ -282,10 +326,10 @@ function gate(id, question, passed, measured, threshold, { reason = null, missin
   return { id, question, passed, measured, threshold, reason, missing };
 }
 
-// ─── the six gates ──────────────────────────────────────────────────────────
+// ─── the gates ──────────────────────────────────────────────────────────────
 //
 // Each one holds the verdict on its own and for its own reason. They are
-// written as six independent functions over the same context rather than one
+// written as independent functions over the same context rather than one
 // chain of ifs, because a gate that can only fire when the previous one passed
 // cannot report a run's second problem — and then the run gets repeated to
 // discover it.
@@ -553,12 +597,76 @@ function rejectedGate({ agg, arms, t, journal }) {
   });
 }
 
-const GATES = [sampleGate, homogeneityGate, delegationGate, orderGate, unpricedGate, rejectedGate];
+/**
+ * 7. More than one meter computed this chain, or one that names no code
+ *    (EPIC-010, PO decision 2, frozen 2026-10-15).
+ *
+ * The stamps read are the paired pool's rows (`paired.meter_versions`), the
+ * aggregate's `analyzed_by` and this verdict's own `judged_by` — the whole
+ * chain, because in the EPIC-009 series the measured tasks changed analyze and
+ * verdict themselves, and rows from one version judged by another is the same
+ * error one floor up. Natural work never reaches the verdict, so its stamps are
+ * not read.
+ *
+ * analyze does not refuse mixed stamps (decision 2): the per-pair costs must
+ * stay visible to plan a repeat. So the refusal lives here, and it says which
+ * step carried which stamp — "two meters" alone does not say what to recompute.
+ */
+function meterGate({ agg, paired, judgedBy, t }) {
+  const q = 'Did one identifiable meter compute the whole chain, from the rows to this verdict?';
+  const carriers = new Map();
+  const carry = (stamp, what) => {
+    if (!carriers.has(stamp)) carriers.set(stamp, []);
+    carriers.get(stamp).push(what);
+  };
+  const rows = paired.meter_versions ?? {};
+  for (const [stamp, n] of Object.entries(rows)) carry(stamp, `rows ×${n}`);
+  // A step with no stamp is not a stamp of its own: it is a step nobody can
+  // name, and it holds the gate under that description.
+  const unstamped = [];
+  if (agg.analyzed_by) carry(agg.analyzed_by, 'analyze');
+  else unstamped.push('analyze');
+  if (judgedBy) carry(judgedBy, 'verdict');
+  else unstamped.push('verdict');
+
+  const stamps = [...carriers.keys()].sort();
+  const unidentifiable = Object.fromEntries(
+    stamps.map((stamp) => [stamp, stampProblem(stamp)]).filter(([, problem]) => problem !== null),
+  );
+  const measured = {
+    stamps,
+    carried_by: Object.fromEntries(stamps.map((stamp) => [stamp, carriers.get(stamp)])),
+    rows_by_stamp: { ...rows },
+    analyzed_by: agg.analyzed_by ?? null,
+    judged_by: judgedBy ?? null,
+    unidentifiable,
+    unstamped_steps: unstamped,
+  };
+  if (stamps.length === 1 && Object.keys(unidentifiable).length === 0 && unstamped.length === 0) {
+    return gate('meter_mixed', q, true, measured, t.meter_mixed);
+  }
+
+  const where = (stamp) => `${stamp} (${carriers.get(stamp).join(', ')})`;
+  const reasons = [];
+  if (stamps.length > 1) reasons.push(`the chain was computed by ${stamps.length} meters: ${stamps.map(where).join('; ')}`);
+  for (const [stamp, problem] of Object.entries(unidentifiable)) reasons.push(`${where(stamp)} names no code: ${problem}`);
+  if (unstamped.length > 0) reasons.push(`${unstamped.join(' and ')} left no stamp`);
+  return gate('meter_mixed', q, false, measured, t.meter_mixed, {
+    reason: reasons.join('; '),
+    missing:
+      'the whole chain from one meter that names its code — recompute the rows from the transcripts or from an' +
+      ' archive (`tune-context experiment archive`) with the current version, or run every step with the version' +
+      ' that computed the rows (`npx -p @bglocation/tune-context@<version> tune-context eval …`); a series runs' +
+      ' from a release or a clean commit, never from a .dirty tree',
+  });
+}
+
+const GATES = [sampleGate, homogeneityGate, delegationGate, orderGate, unpricedGate, rejectedGate, meterGate];
 
 /**
  * Aggregate in, decision out.
  *
- * @param agg         the object analyze() returned (schema tune-context/analyze@1).
+ * @param agg         the object analyze() returned (schema tune-context/analyze@2).
  * @param thresholds    the frozen table. Injectable so a test can prove a gate
  *                      READS it rather than repeating the number in code — which
  *                      is the only way to tell a frozen threshold from a
@@ -568,6 +676,11 @@ const GATES = [sampleGate, homogeneityGate, delegationGate, orderGate, unpricedG
  *                      not the same as passing `[]` — see
  *                      normalizeJournalRejects(). A paired pool cannot be ruled
  *                      on while it is omitted.
+ * @param judgedBy      the stamp of the code running this function, from the
+ *                      caller — the same arrangement as report's `generatedAt`,
+ *                      so this stays free of ambient state. Omitted, the
+ *                      meter_mixed gate holds: a verdict nobody can trace to code
+ *                      is the thing EPIC-010 exists to stop.
  *
  * Throws on an input that is not an analyze aggregate: the same layer-boundary
  * rule classifyRow() applies to unannotated rows. A shape this does not
@@ -575,9 +688,15 @@ const GATES = [sampleGate, homogeneityGate, delegationGate, orderGate, unpricedG
  * rejects — i.e. as a withheld verdict, which is the one wrong answer nobody
  * would look at twice.
  */
-export function verdict(agg, { thresholds = VERDICT_THRESHOLDS, rejectedRuns } = {}) {
-  if (!agg || typeof agg !== 'object' || agg.schema !== 'tune-context/analyze@1') {
-    throw new TypeError('verdict: expected an aggregate from analyze() (schema tune-context/analyze@1)');
+export function verdict(agg, { thresholds = VERDICT_THRESHOLDS, rejectedRuns, judgedBy = null } = {}) {
+  if (!agg || typeof agg !== 'object' || agg.schema !== 'tune-context/analyze@2') {
+    // An @1 aggregate is refused, not upgraded: its rows carry no stamp, and the
+    // only way back to that data is through the transcripts (EPIC-010 decision 4).
+    const got = agg && typeof agg === 'object' && typeof agg.schema === 'string' ? ` — got ${agg.schema}` : '';
+    throw new VerdictInputError(
+      `verdict: expected an aggregate from analyze() (schema tune-context/analyze@2)${got}; recompute it with` +
+        ' `tune-context eval analyze` from stamped rows (EPIC-010: unstamped data is not used)',
+    );
   }
   const paired = agg.paired;
   const arms = paired.arms;
@@ -585,7 +704,7 @@ export function verdict(agg, { thresholds = VERDICT_THRESHOLDS, rejectedRuns } =
   const effects = pairEffects(paired.pairs);
   const journal = normalizeJournalRejects(rejectedRuns);
 
-  const ctx = { agg, paired, arms, effects, t, journal };
+  const ctx = { agg, paired, arms, effects, t, journal, judgedBy };
   const gates = GATES.map((fn) => fn(ctx));
   const holds = gates.filter((g) => !g.passed);
   // Three outcomes, named, because two of them are not "cheaper arm" and
@@ -603,8 +722,11 @@ export function verdict(agg, { thresholds = VERDICT_THRESHOLDS, rejectedRuns } =
   const ruled = finding !== 'withheld';
 
   return {
-    schema: 'tune-context/verdict@1',
+    schema: 'tune-context/verdict@2',
     pool: 'paired',
+    // Which code judged — read by the meter_mixed gate above, and kept here so
+    // a verdict read a year later still names it.
+    judged_by: judgedBy,
     // The table travels with the decision: a verdict read six months later has
     // to show which thresholds it was judged against, without anyone trusting
     // that the file still says the same thing.
@@ -637,3 +759,205 @@ export function verdict(agg, { thresholds = VERDICT_THRESHOLDS, rejectedRuns } =
     observation_only: true,
   };
 }
+
+// ─── text ───────────────────────────────────────────────────────────────────
+
+const pctText = (x) => (Number.isFinite(x) ? `${(x * 100).toFixed(1)}%` : '—');
+
+/**
+ * Per gate: what was measured, against what. One entry per gate in GATES — a
+ * test holds the two lists equal, so a new gate cannot reach the terminal as a
+ * bare id. Kept here rather than in the gates, because a gate's job is to
+ * decide and this is only how a decision reads at 80 columns.
+ */
+const GATE_SUMMARIES = {
+  sample: (m, t) =>
+    `${m.n_pairs_complete} complete pair(s), sessions off ${m.sessions_per_arm.off} / on ${m.sessions_per_arm.on}; floor ${t.min_pairs}`,
+  homogeneity: (m) => `model ${m.distinct_models.join(', ') || '—'}, effort ${m.distinct_efforts.join(', ') || '—'}; must be identical`,
+  delegation: (m, t) =>
+    `spawns off ${m.spawns_by_arm.off} / on ${m.spawns_by_arm.on}` +
+    (m.direction_known ? `, cheaper arm ${m.cheaper_arm} +${m.diff}; max +${t.max_diff}` : ', no cheaper arm'),
+  order_effect: (m, t) =>
+    m.arm_effect_usd === null || m.order_effect_usd === null
+      ? `no usable pair; needs |arm| >= ${t.min_arm_over_order}x |order|`
+      : `arm ${formatUsd(m.arm_effect_usd)}, order ${formatUsd(m.order_effect_usd)}, ratio ${m.ratio ?? '—'}x; needs >= ${t.min_arm_over_order}x`,
+  unpriced: (m, t) => `${m.unpriced_rows} unpriced row(s); max ${t.max_rows}`,
+  rejected: (m, t) =>
+    `${pctText(m.share)} rejected (${m.rejected_rows} of ${m.rows_in_pool} row(s)), journal ` +
+    `${m.operator_rejects === 'NOT REPORTED' ? 'NOT REPORTED' : `${m.operator_rejects} row(s)`}; max ${pctText(t.max_share)}`,
+  meter_mixed: (m) =>
+    `${m.stamps.map((stamp) => `${stamp} (${m.carried_by[stamp].join(', ')})`).join('; ') || 'no stamp'}` +
+    `${m.unstamped_steps.length > 0 ? `, unstamped: ${m.unstamped_steps.join(', ')}` : ''}; one identifiable stamp`,
+};
+
+/**
+ * The verdict as text, for stderr: one line per gate — passed or held, what it
+ * measured against its threshold, and why it holds — then the finding in one
+ * word. Every gate, always, in the order verdict() evaluated them, for the same
+ * reason verdict() evaluates them all: a reader who fixes one problem and
+ * reruns has paid a run to learn about the second.
+ *
+ * Pure: a verdict in, a string out.
+ */
+export function formatVerdict(v) {
+  const L = [`verdict: paired pool, ${v.n_pairs_used} usable pair(s) — an observation, never proof`];
+  for (const g of v.gates) {
+    const summary = GATE_SUMMARIES[g.id]?.(g.measured, g.threshold) ?? '';
+    L.push(`  ${g.passed ? '✓' : '✗'} ${g.id.padEnd(12)} ${summary}${g.passed ? '' : ` — ${g.reason}`}`);
+  }
+  // Said on its own line, because it is the one hold the operator causes by
+  // omission: the flag was not passed, so nobody asked the journal.
+  const journal = v.gates.find((g) => g.id === 'rejected');
+  if (journal && !journal.passed && journal.measured.operator_rejects === 'NOT REPORTED') {
+    L.push(
+      '  ! no --rejected-runs: nobody asked the run journal, so gate `rejected` holds by construction —' +
+        ' pass its §7 rejections, or a file containing [] once the journal has been read',
+    );
+  }
+  L.push(
+    `finding: ${
+      v.finding === 'withheld'
+        ? `withheld: ${v.holds.length} gate(s) hold — ${v.holds.map((g) => g.id).join(', ')}`
+        : v.finding === 'no-difference'
+          ? 'no-difference'
+          : `cheaper-arm: ${v.cheaper_arm}`
+    }`,
+  );
+  return L.join('\n');
+}
+
+// ─── CLI ────────────────────────────────────────────────────────────────────
+//
+// The only I/O in this file (see the header). `eval verdict` and `eval report`
+// both judge, so both read their input through readVerdictInput() below.
+
+const USAGE = `
+verdict — may this run say "one arm is cheaper"? The gates over an analyze aggregate (TASK-090).
+
+Usage:
+  verdict [--aggregate <path>] [--rejected-runs <path>]
+
+Options:
+  --aggregate <path>      JSON written by analyze (default: read stdin)
+  --rejected-runs <path>  JSON array of the run journal's §7 rejections,
+                          [{ session, task, arm, prompts, reason }]. OMITTING it
+                          is not the same as passing a file containing []: the
+                          first says nobody asked the journal, and gate 6 holds
+                          the verdict for it. Same flag, same meaning as report.
+  -h, --help              Show this help
+
+Writes the verdict as JSON to stdout — the same object report embeds in its
+HTML — and one line per gate to stderr. Exit 0 for every verdict, a withheld one
+included: withholding is an answer, not a failure. Exit 1 only when the input
+cannot be read.
+`.trim();
+
+/**
+ * A file the CLI was pointed at, as text — or the VerdictInputError naming the
+ * flag: missing, a directory, unreadable. Asking existsSync first let a
+ * directory through to readFileSync, and up as an EISDIR stacktrace.
+ */
+function readInputFile(path, flag) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch (e) {
+    throw new VerdictInputError(e.code === 'ENOENT' ? `no file at ${path} (${flag})` : `cannot read ${path} (${flag}): ${e.message}`);
+  }
+}
+
+function parseJson(text, what) {
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new VerdictInputError(`${what} is not JSON: ${e.message}`);
+  }
+}
+
+/**
+ * The aggregate and the run journal, read and checked in ONE place for both
+ * steps that judge. Two copies would drift, and the drift nobody notices is the
+ * report accepting an input the verdict refuses.
+ *
+ * @param aggregate     a path, or undefined to read stdin
+ * @param rejectedRuns  a path, or undefined — and undefined STAYS undefined. It
+ *                      means nobody asked the journal, which gate 6 holds on;
+ *                      defaulting it to [] here would pass that gate on a share
+ *                      whose denominator nobody supplied.
+ * @returns {Promise<{agg: object, rejectedRuns: object[]|undefined}>}
+ * @throws {VerdictInputError} a file that is missing, a directory or
+ *         unreadable, a file that is not JSON, or a journal of the wrong shape —
+ *         the message names the flag and the path.
+ *         Whether the aggregate IS an aggregate is verdict()'s check, the same
+ *         one a module caller gets.
+ */
+export async function readVerdictInput({ aggregate, rejectedRuns }) {
+  // Both files before stdin: a mistyped --rejected-runs is reported at once,
+  // not after the aggregate has been piped in.
+  const aggText = aggregate === undefined ? undefined : readInputFile(aggregate, '--aggregate');
+  const runsText = rejectedRuns === undefined ? undefined : readInputFile(rejectedRuns, '--rejected-runs');
+  const agg =
+    aggText === undefined ? parseJson(await readStdin(), 'the aggregate on stdin') : parseJson(aggText, `--aggregate ${aggregate}`);
+  if (runsText === undefined) return { agg, rejectedRuns: undefined };
+  const runs = parseJson(runsText, `--rejected-runs ${rejectedRuns}`);
+  const problem = journalShapeProblem(runs);
+  if (problem !== null) throw new VerdictInputError(`--rejected-runs ${rejectedRuns}: ${problem}`);
+  return { agg, rejectedRuns: runs };
+}
+
+/**
+ * The line an input error prints: the step's name, then the message — unless
+ * the message already names this step (verdict()'s own errors start with
+ * `verdict:`), so `eval verdict` never stutters while `eval report` still says
+ * which layer refused.
+ */
+export function inputErrorLine(step, error) {
+  return error.message.startsWith(`${step}: `) ? error.message : `${step}: ${error.message}`;
+}
+
+/**
+ * The CLI. `args` is everything after the script name, or after
+ * `tune-context eval verdict` — one parser behind both doors (EPIC-010).
+ */
+export async function main(args = process.argv.slice(2)) {
+  endQuietlyOnClosedPipe();
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args,
+      options: {
+        aggregate: { type: 'string' },
+        'rejected-runs': { type: 'string' },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+    }));
+  } catch (e) {
+    process.stderr.write(`verdict: ${e.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  let v;
+  try {
+    const { agg, rejectedRuns } = await readVerdictInput({ aggregate: values.aggregate, rejectedRuns: values['rejected-runs'] });
+    v = verdict(agg, { rejectedRuns, judgedBy: meterStamp() });
+  } catch (e) {
+    // Exactly the input boundary. A TypeError from inside a gate is a bug and
+    // keeps its stacktrace.
+    if (!(e instanceof VerdictInputError)) throw e;
+    process.stderr.write(`${inputErrorLine('verdict', e)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write(`${JSON.stringify(v, null, 2)}\n`);
+  process.stderr.write(`${formatVerdict(v)}\n`);
+}
+
+if (isEntryPoint(import.meta.url)) {
+  await main();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bglocation/tune-context",
-  "version": "2.5.0",
+  "version": "3.0.0",
   "description": "Context-efficiency configurator for Claude Code — token-saving doctrine packaged as skills, plus a tune-context configurator that scaffolds a lean CLAUDE.md, doctrine skills, subagents, settings, hooks and MCP wiring.",
   "type": "module",
   "license": "MIT",

package/skills/token-efficiency/SKILL.md

@@ -45,7 +45,7 @@ comments in the domain vocabulary someone would *search* with — better contrac
 ## 6. Measure, don't believe
 If the tool logs usage (`.rag/usage.jsonl` → `rag-usage`), review it
 periodically: is semantic search actually replacing grep? Promote or drop levers
-on data, not faith. If `tune-context` is set up, `node eval/adoption-report.mjs`
+on data, not faith. If `tune-context` is set up, `tune-context eval adoption-report`
 covers the rest of this doctrine the same way — search lever, skills, subagents,
 re-read churn — as a behavioral proxy (tool calls), not token cost.
 

package/skills/tune-context/SKILL.md

@@ -156,8 +156,10 @@ covering the detected build/test/lint commands.
      they fire their own event carrying `agent_type`). It appends one line per
      event to `~/.claude/tune-context/adoption.jsonl` by default — which lever the
      model reached for (RAG vs grep, Skill, subagent, re-reads). Read it with
-     `eval/adoption-report.mjs` (the `rag-usage` analog). Behavioral proxy only:
-     no token cost (needs OTEL `claude_code.cost.usage` + a collector) and no
+     `tune-context eval adoption-report` (module `eval/adoption-report.mjs`; the
+     `rag-usage` analog). Behavioral proxy only:
+     no token cost (that is `tune-context eval prompt-metrics`, from the session
+     transcripts; OTEL `claude_code.cost.usage` is Anthropic's own figure) and no
      caveman (an output style, not a tool call). Doctrine-as-method (narrow reads,
      contracts-first edits) is likewise not `Skill`-call-visible — the verdict
      reports zero `Skill` calls as a neutral note, not "unused", and points at the