@trazum/cli 1.50.7 → 1.50.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.50.7",
+  "version": "1.50.9",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.50.7"
+    "@trazum/core": "1.50.9"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -59,6 +59,8 @@ ${bold('USAGE')}
   trazum rules
   trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
   trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
+  trazum quality <log> --label <name> --at <iso> [--gate]
+  trazum semantic <prompt> [--yes]
   trazum ladder <log>
   trazum feedback
   trazum --version
@@ -132,6 +134,31 @@ ${bold('OPTIONS FOR experiment')}
   not separable — with the number of outcomes per arm that would settle it, so
   "run it longer" is an instruction rather than a shrug. Nothing is promoted.
 
+${bold('OPTIONS FOR quality')}
+  --label <name>              The workload to judge. Required: a mixture would
+                              average a regression away.
+  --at <iso>                  When the change landed. Required: without a
+                              boundary there is nothing to compare across, and
+                              picking one would be this tool choosing which
+                              change to blame.
+  --gate                      Exit 1 on a measured drop, 2 on "cannot tell".
+                              Three outcomes, never two.
+
+  A before-and-after rather than an experiment, so it reports "cannot tell"
+  whenever the model mix, the call volume or the outcome coverage moved across
+  the boundary — the prompt is not the only variable and it says so.
+
+${bold('OPTIONS FOR semantic')}
+  --yes                       Required to send anything. Without it the command
+                              prints what the call would cost and stops.
+  --model <id>                Which model to ask. Priced from the catalogue.
+
+  Finds what a dictionary cannot: the same rule taught twice in different
+  words, an instruction restated far away, a policy a later clause contradicts.
+  Every quoted passage is checked character for character against the prompt,
+  pairs the rules engine already catches are dropped, and every token figure is
+  counted rather than believed. Optional, and always will be.
+
 ${bold('OPTIONS FOR prune')}
   --cases <file>              One input per line, or a JSON array. Required.
   --yes                       Actually spend the calls. Without it the estimate is
@@ -977,6 +1004,73 @@ ${bold('EXAMPLES')}
       `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
   },
 
+  semantic: {
+    heading: (path) => `Semantic pass on ${path}`,
+    willCost: (usd, input, output, model) =>
+      `This will send the prompt to ${model}: about ${input} tokens in and ${output} out, roughly ${usd}. Estimated, not measured \u2014 a tool that spends your money to tell you how to spend less should be the first thing audited by its own arithmetic. Pass --yes to run it.`,
+    needsYes: () => 'Nothing was sent. Add --yes once you have read the price above.',
+    finding: (kind, because) =>
+      `${kind === 'contradiction' ? 'Contradiction' : kind === 'restated-instruction' ? 'Restated' : 'Same thing, different words'}: ${because}`,
+    span: (line, text) => `line ${line}: ${text}`,
+    ceiling: (tokens) =>
+      `At most ${tokens} tokens \u2014 a ceiling, not a saving. Merging these two means writing one passage that does the work of both, and nobody knows yet how long that is.`,
+    noCeiling: () =>
+      'No tokens attached. A contradiction is worth fixing because the prompt is wrong, not because it is long, and putting a figure on it would sell the wrong reason.',
+    nothingFound: () => 'Nothing survived checking. That is a real answer.',
+    rejected: (count) => `${count} proposals did not survive checking against the prompt.`,
+    rejectedLine: (reason, span) =>
+      reason === 'span-not-found'
+        ? `paraphrased its own evidence: ${span}`
+        : reason === 'already-detected'
+          ? `already found without a model: ${span}`
+          : reason === 'contradiction-of-a-copy'
+            ? `called a near-copy a contradiction: ${span}`
+            : reason === 'spans-identical' || reason === 'spans-overlap'
+              ? `quoted the same passage twice: ${span}`
+              : `covers ground an accepted finding covers: ${span}`,
+    disposes: () =>
+      'The model proposes and the deterministic layer disposes: every quoted passage is checked character for character against the prompt, pairs the rules engine already catches are dropped, and every token figure is counted here rather than believed.',
+    optIn: () =>
+      'This pass is optional and always will be. Trazum works with no key, no network and no model \u2014 that has been true since 0.1.0 and this does not change it.',
+  },
+
+  quality: {
+    heading: (label) => `Quality across the change: ${label}`,
+    needsLabel: () => 'Name the workload with --label: this compares one label before and after a change, and a mixture of workloads would average a regression away.',
+    needsAt: () =>
+      '--at is required: give the moment the change landed, as an ISO timestamp. Without it there is no boundary to compare across, and picking one from the log would be this tool choosing which change to blame.',
+    sides: (beforeRate, afterRate, before, after) =>
+      `before ${beforeRate} (${before} outcomes)   after ${afterRate} (${after} outcomes)`,
+    dropped: (from, to, outcomes, cost) =>
+      `The resolution rate moved from ${from} to ${to} on ${outcomes} measured outcomes, and this change ${cost}. Both halves are measured; neither is an estimate.`,
+    held: (from, to, outcomes) =>
+      `The resolution rate moved from ${from} to ${to} on ${outcomes} measured outcomes \u2014 up, measurably.`,
+    cannotTell: (why, need) =>
+      why === 'too-few-before'
+        ? `Cannot tell: only ${need} outcomes before the change, and this gate needs 100 a side. It fails builds, so the threshold is not the one a rate uses elsewhere.`
+        : why === 'too-few-after'
+          ? `Cannot tell yet: only ${need} outcomes since the change, and this gate needs 100 a side. Run it again once the traffic has caught up.`
+          : why === 'not-separable'
+            ? 'Cannot tell: the rate did not measurably move. That is NOT the same as "it held" \u2014 a gate that spelled them the same way would pass a real regression it merely lacked the power to see.'
+            : why === 'no-vocabulary'
+              ? 'Cannot tell: "outcomes.success" declares nothing, so there is no resolution rate to compare.'
+              : 'Cannot tell: something other than the prompt moved across the boundary. See below.',
+    confoundersHeading: () => 'The prompt is not the only thing that changed',
+    confounder: (kind, detail) =>
+      kind === 'model-mix-moved'
+        ? `The model mix moved by ${detail}. The drop may be entirely somebody else's migration, and this tool cannot separate the two.`
+        : kind === 'volume-moved'
+          ? `The call volume moved ${detail}. A workload whose traffic moved that much is usually a workload whose population changed \u2014 a new surface, a new customer, a campaign \u2014 and the questions being asked are not the questions from before.`
+          : `Outcome coverage moved from ${detail}. The two rates describe different populations: a team that starts instrumenting its hard cases sees its measured rate fall without anything having got worse.`,
+    notRandomised: () =>
+      'This is a before-and-after, not an experiment. It splits traffic by time rather than at random, so everything else that changed at the same time is in the difference too \u2014 which is why it says "cannot tell" far more readily than an A/B would.',
+    cannotSee: () =>
+      'It cannot see anything else you deployed that day. A "dropped" verdict says the rate fell and the three things it can check did not move. That is a smaller claim than "the prompt did it", and it is the largest one the evidence supports.',
+    gateFailed: () => 'Gate failed: a measured drop with nothing else to explain it.',
+    gateHeldOpen: () =>
+      'Gate not passed and not failed. "Cannot tell" holds the claim open rather than exiting green \u2014 the posture verify has had since 1.39.',
+  },
+
   experiment: {
     heading: (a, b) => `Experiment: ${a} against ${b}`,
     needsTwo: () =>

package/src/i18n/es.ts

@@ -46,6 +46,8 @@ ${bold('USO')}
   trazum rules
   trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
   trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
+  trazum quality <log> --label <name> --at <iso> [--gate]
+  trazum semantic <prompt> [--yes]
   trazum ladder <log>
   trazum feedback
   trazum --version
@@ -122,6 +124,31 @@ ${bold('OPCIONES DE experiment')}
   o no separables — con cuántos resultados por brazo lo zanjarían, para que
   "déjalo correr más" sea una instrucción y no un encogimiento de hombros.
 
+${bold('OPCIONES DE quality')}
+  --label <nombre>            La carga a juzgar. Obligatorio: una mezcla
+                              promediaría una regresión hasta hacerla
+                              desaparecer.
+  --at <iso>                  Cuándo aterrizó el cambio. Obligatorio: sin
+                              frontera no hay nada que comparar, y elegir una
+                              sería que esta herramienta decida a qué culpar.
+  --gate                      Sale con 1 si hay caída medida, 2 si no se puede
+                              decir. Tres resultados, nunca dos.
+
+  Un antes y después, no un experimento, así que dice "no se puede decir"
+  siempre que la mezcla de modelos, el volumen o la cobertura se movieran a
+  través de la frontera — el prompt no es la única variable y lo dice.
+
+${bold('OPCIONES DE semantic')}
+  --yes                       Obligatorio para enviar nada. Sin él, el comando
+                              imprime lo que costaría la llamada y para.
+  --model <id>                Qué modelo preguntar. Se tarifa del catálogo.
+
+  Encuentra lo que un diccionario no puede: la misma regla enseñada dos veces
+  con otras palabras, una instrucción repetida lejos, una política que una
+  cláusula posterior contradice. Cada pasaje citado se comprueba carácter a
+  carácter contra el prompt, los pares que el motor de reglas ya caza se
+  descartan, y toda cifra de tokens se cuenta en vez de creérsela.
+
 ${bold('OPCIONES DE prune')}
   --cases <fichero>           Una entrada por línea, o un array JSON. Obligatorio.
   --yes                       Gasta las llamadas de verdad. Sin él se imprime la
@@ -1013,6 +1040,73 @@ ${bold('EJEMPLOS')}
       `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
   },
 
+  semantic: {
+    heading: (path) => `Pase sem\u00e1ntico sobre ${path}`,
+    willCost: (usd, input, output, model) =>
+      `Esto enviar\u00e1 el prompt a ${model}: unos ${input} tokens de entrada y ${output} de salida, aproximadamente ${usd}. Estimado, no medido \u2014 una herramienta que gasta tu dinero para decirte c\u00f3mo gastar menos deber\u00eda ser lo primero que audite su propia aritm\u00e9tica. Pasa --yes para ejecutarlo.`,
+    needsYes: () => 'No se envi\u00f3 nada. A\u00f1ade --yes cuando hayas le\u00eddo el precio de arriba.',
+    finding: (kind, because) =>
+      `${kind === 'contradiction' ? 'Contradicci\u00f3n' : kind === 'restated-instruction' ? 'Repetido' : 'Lo mismo con otras palabras'}: ${because}`,
+    span: (line, text) => `l\u00ednea ${line}: ${text}`,
+    ceiling: (tokens) =>
+      `Como mucho ${tokens} tokens \u2014 un techo, no un ahorro. Fundir los dos significa escribir un pasaje que haga el trabajo de ambos, y nadie sabe todav\u00eda cu\u00e1nto ocupa.`,
+    noCeiling: () =>
+      'Sin tokens asociados. Una contradicci\u00f3n merece arreglarse porque el prompt est\u00e1 mal, no porque sea largo, y ponerle una cifra vender\u00eda el motivo equivocado.',
+    nothingFound: () => 'Nada sobrevivi\u00f3 a la comprobaci\u00f3n. Esa es una respuesta real.',
+    rejected: (count) => `${count} propuestas no sobrevivieron a la comprobaci\u00f3n contra el prompt.`,
+    rejectedLine: (reason, span) =>
+      reason === 'span-not-found'
+        ? `parafrase\u00f3 su propia evidencia: ${span}`
+        : reason === 'already-detected'
+          ? `ya se encuentra sin modelo: ${span}`
+          : reason === 'contradiction-of-a-copy'
+            ? `llam\u00f3 contradicci\u00f3n a una casi copia: ${span}`
+            : reason === 'spans-identical' || reason === 'spans-overlap'
+              ? `cit\u00f3 el mismo pasaje dos veces: ${span}`
+              : `cubre terreno que ya cubre un hallazgo aceptado: ${span}`,
+    disposes: () =>
+      'El modelo propone y la capa determinista dispone: cada pasaje citado se comprueba car\u00e1cter a car\u00e1cter contra el prompt, los pares que el motor de reglas ya caza se descartan, y toda cifra de tokens se cuenta aqu\u00ed en vez de cre\u00e9rsela.',
+    optIn: () =>
+      'Este pase es opcional y siempre lo ser\u00e1. Trazum funciona sin clave, sin red y sin modelo \u2014 eso es cierto desde 0.1.0 y esto no lo cambia.',
+  },
+
+  quality: {
+    heading: (label) => `Calidad a trav\u00e9s del cambio: ${label}`,
+    needsLabel: () => 'Nombra la carga con --label: esto compara una etiqueta antes y despu\u00e9s de un cambio, y una mezcla de cargas promediar\u00eda una regresi\u00f3n hasta hacerla desaparecer.',
+    needsAt: () =>
+      '--at es obligatorio: da el momento en que aterriz\u00f3 el cambio, como marca ISO. Sin \u00e9l no hay frontera que comparar, y elegir una del log ser\u00eda que esta herramienta decida a qu\u00e9 cambio culpar.',
+    sides: (beforeRate, afterRate, before, after) =>
+      `antes ${beforeRate} (${before} resultados)   despu\u00e9s ${afterRate} (${after} resultados)`,
+    dropped: (from, to, outcomes, cost) =>
+      `La tasa de resoluci\u00f3n pas\u00f3 de ${from} a ${to} sobre ${outcomes} resultados medidos, y este cambio ${cost}. Las dos mitades son medidas; ninguna es una estimaci\u00f3n.`,
+    held: (from, to, outcomes) =>
+      `La tasa de resoluci\u00f3n pas\u00f3 de ${from} a ${to} sobre ${outcomes} resultados medidos \u2014 arriba, de forma medible.`,
+    cannotTell: (why, need) =>
+      why === 'too-few-before'
+        ? `No se puede decir: solo ${need} resultados antes del cambio, y esta puerta necesita 100 por lado. Falla builds, as\u00ed que el umbral no es el que usa una tasa en otros sitios.`
+        : why === 'too-few-after'
+          ? `A\u00fan no se puede decir: solo ${need} resultados desde el cambio, y esta puerta necesita 100 por lado. Vuelve a correrlo cuando el tr\u00e1fico se ponga al d\u00eda.`
+          : why === 'not-separable'
+            ? 'No se puede decir: la tasa no se movi\u00f3 de forma medible. Eso NO es lo mismo que "se mantuvo" \u2014 una puerta que las escribiera igual dejar\u00eda pasar una regresi\u00f3n real que simplemente no tuvo potencia para ver.'
+            : why === 'no-vocabulary'
+              ? 'No se puede decir: "outcomes.success" no declara nada, as\u00ed que no hay tasa de resoluci\u00f3n que comparar.'
+              : 'No se puede decir: algo que no es el prompt se movi\u00f3 a trav\u00e9s de la frontera. Ver abajo.',
+    confoundersHeading: () => 'El prompt no es lo \u00fanico que cambi\u00f3',
+    confounder: (kind, detail) =>
+      kind === 'model-mix-moved'
+        ? `La mezcla de modelos se movi\u00f3 un ${detail}. La ca\u00edda puede ser enteramente la migraci\u00f3n de otra persona, y esta herramienta no puede separarlas.`
+        : kind === 'volume-moved'
+          ? `El volumen de llamadas se movi\u00f3 ${detail}. Una carga cuyo tr\u00e1fico se mueve tanto suele ser una carga cuya poblaci\u00f3n cambi\u00f3 \u2014 una superficie nueva, un cliente nuevo, una campa\u00f1a \u2014 y las preguntas que se hacen no son las de antes.`
+          : `La cobertura de resultados pas\u00f3 de ${detail}. Las dos tasas describen poblaciones distintas: un equipo que empieza a instrumentar sus casos dif\u00edciles ve caer su tasa medida sin que nada haya empeorado.`,
+    notRandomised: () =>
+      'Esto es un antes y despu\u00e9s, no un experimento. Parte el tr\u00e1fico por tiempo y no al azar, as\u00ed que todo lo dem\u00e1s que cambi\u00f3 a la vez est\u00e1 tambi\u00e9n en la diferencia \u2014 por eso dice "no se puede decir" mucho m\u00e1s f\u00e1cilmente que un A/B.',
+    cannotSee: () =>
+      'No puede ver nada m\u00e1s que desplegaras ese d\u00eda. Un veredicto de "ca\u00edda" dice que la tasa baj\u00f3 y que las tres cosas que puede comprobar no se movieron. Es una afirmaci\u00f3n m\u00e1s peque\u00f1a que "lo hizo el prompt", y es la mayor que sostiene la evidencia.',
+    gateFailed: () => 'Puerta fallada: una ca\u00edda medida sin nada m\u00e1s que la explique.',
+    gateHeldOpen: () =>
+      'Puerta ni pasada ni fallada. "No se puede decir" mantiene la afirmaci\u00f3n abierta en vez de salir en verde \u2014 la postura de verify desde 1.39.',
+  },
+
   experiment: {
     heading: (a, b) => `Experimento: ${a} contra ${b}`,
     needsTwo: () =>

package/src/i18n/types.ts

@@ -268,6 +268,37 @@ export interface CliMessages {
    * The ladder. Every line here exists to stop somebody reading "we route to
    * the cheap model first" as a saving without the number that decides it.
    */
+  semantic: {
+    heading(path: string): string;
+    willCost(usd: string, input: string, output: string, model: string): string;
+    needsYes(): string;
+    finding(kind: string, because: string): string;
+    span(line: string, text: string): string;
+    ceiling(tokens: string): string;
+    noCeiling(): string;
+    nothingFound(): string;
+    rejected(count: string): string;
+    rejectedLine(reason: string, span: string): string;
+    disposes(): string;
+    optIn(): string;
+  };
+
+  quality: {
+    heading(label: string): string;
+    needsLabel(): string;
+    needsAt(): string;
+    sides(beforeRate: string, afterRate: string, before: string, after: string): string;
+    dropped(from: string, to: string, outcomes: string, cost: string): string;
+    held(from: string, to: string, outcomes: string): string;
+    cannotTell(why: string, need: string): string;
+    confounder(kind: string, detail: string): string;
+    confoundersHeading(): string;
+    notRandomised(): string;
+    cannotSee(): string;
+    gateFailed(): string;
+    gateHeldOpen(): string;
+  };
+
   experiment: {
     heading(a: string, b: string): string;
     needsTwo(): string;

package/src/index.ts

@@ -41,6 +41,10 @@ import {
   conform,
   BREAK_EVEN_BAND,
   runExperiment,
+  qualityGate,
+  semanticPassCost,
+  verifySemanticProposals,
+  SEMANTIC_SYSTEM_PROMPT,
   ladderPosition,
   validateLadder,
   outcomeReport,
@@ -141,6 +145,8 @@ import type {
   BudgetReport,
   ContractName,
   ExperimentArm,
+  GateSide,
+  SemanticProposal,
   FailurePolicy,
   GatewayStanding,
   UsageProfileReport,
@@ -248,6 +254,7 @@ interface Args {
 
 const VALUE_FLAGS = new Set([
   'a',
+  'at',
   'b',
   'min-outcomes',
   'against',
@@ -580,6 +587,8 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   gateway: ['on-cannot-tell', 'port', 'socket', 'pricing', 'pricing-live'],
   ladder: ['pricing', 'pricing-live', 'since', 'until', 'label'],
   experiment: ['a', 'b', 'min-outcomes', 'pricing', 'pricing-live'],
+  quality: ['label', 'at', 'gate', 'pricing', 'pricing-live'],
+  semantic: ['yes', 'model', 'pricing', 'pricing-live'],
   where: [],
   rules: [],
   blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -2459,6 +2468,272 @@ async function commandExperiment(
   console.log();
 }
 
+/**
+ * `trazum quality <log> --label <name> --at <iso> [--gate]`
+ *
+ * The failure that actually matters: a prompt edit that quietly made the
+ * product worse. CI has been able to fail a build for tokens since 1.4 and for
+ * dollars since 1.21, and this has never been gateable — so every saving this
+ * tool has ever recommended went into a repository with its most important
+ * consequence unmeasured.
+ *
+ * **Named `quality` rather than `check --against-outcomes`, which is what the
+ * plan called for.** `check` reads *prompt files* and gates on tokens; it has
+ * never opened a usage log, and a command that takes either a prompt or a log
+ * depending on a flag is two commands wearing one name. The split-by-time this
+ * needs is also not a `check` idea — there is nothing in a prompt file with a
+ * timestamp on it.
+ */
+async function commandQuality(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const path = args.positional[0];
+  if (path === undefined) throw new Error(t.errors.missingInputFile());
+
+  const label = stringFlag(args, 'label');
+  if (label === undefined) throw new Error(t.quality.needsLabel());
+
+  const atRaw = stringFlag(args, 'at');
+  const atMs = atRaw === undefined ? Number.NaN : Date.parse(atRaw);
+  if (!Number.isFinite(atMs)) throw new Error(t.quality.needsAt());
+
+  /**
+   * Two profiles over the same file, split at the boundary — rather than one
+   * profile the caller has to slice.
+   *
+   * The alternative is asking somebody for two logs, which invites the mistake
+   * this whole module exists to avoid: two files gathered under conditions
+   * nobody wrote down.
+   */
+  const raw = await readUsageLog(path, t);
+  const sideOf = (since: number | undefined, until: number | undefined): GateSide => {
+    const report = profileUsage(raw, { catalogue: pricing, label, sinceMs: since, untilMs: until });
+    const slice = report.outcomeTallyByLabel.find((entry) => entry.label === label);
+    return {
+      arm: {
+        name: label,
+        totalUsd: report.total.totalUsd,
+        tally: slice?.tally ?? { byValue: [], recorded: 0, parsed: 0, unrecordedUsd: 0 },
+      },
+      calls: report.total.calls,
+      usdByModel: report.byModel.map((entry) => ({ model: entry.model, usd: entry.breakdown.totalUsd })),
+    };
+  };
+
+  const result = qualityGate(sideOf(undefined, atMs), sideOf(atMs, undefined), config.outcomes ?? null);
+  const pct = (value: number): string => `${(value * 100).toFixed(1)}%`;
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+
+  console.log();
+  console.log(c.bold(t.quality.heading(label)));
+  console.log(`  ${c.dim(wrap(t.quality.notRandomised(), 74, '  '))}`);
+  console.log();
+  console.log(
+    `  ${t.quality.sides(
+      result.before.rate === null ? '—' : pct(result.before.rate),
+      result.after.rate === null ? '—' : pct(result.after.rate),
+      n(result.outcomes.before),
+      n(result.outcomes.after),
+    )}`,
+  );
+  console.log();
+
+  if (result.verdict === 'dropped') {
+    const cost =
+      result.cost === null
+        ? ''
+        : result.cost.deltaUsdPerCall < 0
+          ? `saves ${formatUsd(-result.cost.deltaUsdPerCall)} a call`
+          : `costs ${formatUsd(result.cost.deltaUsdPerCall)} a call more`;
+    console.log(
+      `  ${c.red('✗')} ${wrap(
+        t.quality.dropped(
+          pct(result.before.rate ?? 0),
+          pct(result.after.rate ?? 0),
+          n(result.outcomes.before + result.outcomes.after),
+          cost,
+        ),
+        74,
+        '    ',
+      )}`,
+    );
+  } else if (result.verdict === 'held') {
+    console.log(
+      `  ${c.green('✓')} ${wrap(
+        t.quality.held(pct(result.before.rate ?? 0), pct(result.after.rate ?? 0), n(result.outcomes.before + result.outcomes.after)),
+        74,
+        '    ',
+      )}`,
+    );
+  } else {
+    const need =
+      result.unknown === 'too-few-before' ? n(result.outcomes.before) : n(result.outcomes.after);
+    console.log(`  ${c.yellow('?')} ${wrap(t.quality.cannotTell(result.unknown ?? '', need), 74, '    ')}`);
+  }
+
+  /**
+   * Confounders print on **every** verdict, not only on `cannot-tell`.
+   *
+   * A rate that held while the model changed underneath is not evidence that
+   * the prompt is fine either, and hiding the confounder on a green result is
+   * how a gate teaches people to trust it in exactly the case it should not be
+   * trusted.
+   */
+  if (result.confounders.length > 0) {
+    console.log();
+    console.log(`  ${c.bold(t.quality.confoundersHeading())}`);
+    for (const confounder of result.confounders) {
+      const detail =
+        confounder.kind === 'model-mix-moved'
+          ? `${pct(confounder.drift)} (${confounder.model})`
+          : confounder.kind === 'volume-moved'
+            ? `${n(confounder.beforeCalls)} → ${n(confounder.afterCalls)} calls`
+            : `${pct(confounder.before)} → ${pct(confounder.after)}`;
+      console.log(`    ${c.yellow('!')} ${wrap(t.quality.confounder(confounder.kind, detail), 70, '      ')}`);
+    }
+  }
+
+  console.log();
+  console.log(`  ${c.dim(wrap(t.quality.cannotSee(), 74, '  '))}`);
+
+  if (boolFlag(args, 'gate')) {
+    console.log();
+    if (result.verdict === 'dropped') {
+      console.log(`  ${c.red(t.quality.gateFailed())}`);
+      process.exitCode = 1;
+    } else if (result.verdict === 'cannot-tell') {
+      // Three outcomes, never two. `cannot tell` holds the claim open rather
+      // than exiting green, the posture `verify --gate` has had since 1.39.
+      console.log(`  ${c.yellow(t.quality.gateHeldOpen())}`);
+      process.exitCode = 2;
+    }
+  }
+  console.log();
+}
+
+/**
+ * `trazum semantic <prompt> [--yes]` — the findings a dictionary cannot see.
+ *
+ * The rules engine has deferred these since 0.1.0 for one honest reason: a
+ * dictionary cannot see meaning, and a model that hallucinates a finding is
+ * worse than a rule that misses one.
+ *
+ * **The price is printed before anything is sent, and `--yes` is required.** A
+ * tool that spends somebody's money to tell them how to spend less has to be
+ * the first thing audited by its own arithmetic, and it has to ask.
+ */
+async function commandSemantic(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const prompt = await readInput(args.positional[0], t);
+  const modelId = stringFlag(args, 'model') ?? config.usage?.model ?? DEFAULT_USAGE.model;
+  const model = pricing.byId.get(modelId) ?? getModel(DEFAULT_USAGE.model);
+  const rates = { inputPerMTok: model.inputPerMTok, outputPerMTok: model.outputPerMTok };
+  const cost = semanticPassCost(prompt, rates);
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+
+  console.log();
+  console.log(c.bold(t.semantic.heading(args.positional[0] ?? '-')));
+  console.log();
+  console.log(
+    `  ${wrap(
+      t.semantic.willCost(formatUsd(cost.usd), n(cost.inputTokens), n(cost.outputTokens), model.displayName),
+      74,
+      '  ',
+    )}`,
+  );
+
+  if (!boolFlag(args, 'yes')) {
+    // Nothing has been sent at this point, and nothing will be. The price
+    // above is the whole output of a run without --yes.
+    console.log();
+    console.log(`  ${c.dim(t.semantic.needsYes())}`);
+    console.log();
+    return;
+  }
+
+  const provider = providerFromEnv();
+  if (!provider) throw new Error(t.errors.llmNotConfigured());
+
+  const answer = await provider.complete({ system: SEMANTIC_SYSTEM_PROMPT, user: prompt });
+  let proposals: SemanticProposal[] = [];
+  try {
+    const parsed: unknown = JSON.parse(
+      /^(?:```|~~~)[a-zA-Z]*\n([\s\S]*?)\n?(?:```|~~~)$/.exec(answer.trim())?.[1] ?? answer.trim(),
+    );
+    /**
+     * A response that is not the shape asked for is **no proposals**, never a
+     * crash and never a partial read. The model was told exactly what to
+     * return; anything else is a response this layer cannot check, and an
+     * unchecked finding is the one thing this whole module exists to prevent.
+     */
+    if (Array.isArray(parsed)) {
+      proposals = parsed.filter(
+        (entry): entry is SemanticProposal =>
+          typeof entry === 'object' &&
+          entry !== null &&
+          Array.isArray((entry as SemanticProposal).spans) &&
+          (entry as SemanticProposal).spans.length === 2 &&
+          (entry as SemanticProposal).spans.every((span) => typeof span === 'string'),
+      );
+    }
+  } catch {
+    proposals = [];
+  }
+
+  const result = verifySemanticProposals(prompt, proposals);
+  const lineOf = (offset: number): number => prompt.slice(0, offset).split('\n').length;
+
+  console.log();
+  if (result.findings.length === 0) {
+    console.log(`  ${c.dim(t.semantic.nothingFound())}`);
+  }
+  for (const finding of result.findings) {
+    console.log(`  ${c.bold(t.semantic.finding(finding.kind, finding.because))}`);
+    finding.spans.forEach((span, index) => {
+      const shown = span.length > 90 ? `${span.slice(0, 87)}…` : span;
+      console.log(`    ${c.dim(t.semantic.span(String(lineOf(finding.offsets[index] ?? 0)), shown))}`);
+    });
+    console.log(
+      `    ${c.dim(
+        wrap(
+          finding.ceilingTokens > 0 ? t.semantic.ceiling(n(finding.ceilingTokens)) : t.semantic.noCeiling(),
+          70,
+          '    ',
+        ),
+      )}`,
+    );
+    console.log();
+  }
+
+  /**
+   * What did **not** survive, counted and reasoned.
+   *
+   * A pass that showed only its accepted findings would hide its own hit
+   * rate, and the hit rate is the most useful thing a reader can know about
+   * whether to run it again.
+   */
+  if (result.rejected.length > 0) {
+    console.log(`  ${c.dim(t.semantic.rejected(n(result.rejected.length)))}`);
+    for (const { proposal, reason } of result.rejected.slice(0, 5)) {
+      const span = proposal.spans[0];
+      const shown = span.length > 50 ? `${span.slice(0, 47)}…` : span;
+      console.log(`    ${c.dim(t.semantic.rejectedLine(reason, shown))}`);
+    }
+    console.log();
+  }
+
+  console.log(`  ${c.dim(wrap(t.semantic.disposes(), 74, '  '))}`);
+  console.log(`  ${c.dim(wrap(t.semantic.optIn(), 74, '  '))}`);
+  console.log();
+}
+
 function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const col = t.models.columns;
@@ -8659,6 +8934,12 @@ async function main(): Promise<void> {
     case 'models':
       commandModels(t, pricing);
       break;
+    case 'semantic':
+      await commandSemantic(args, config, pricing, t);
+      break;
+    case 'quality':
+      await commandQuality(args, config, pricing, t);
+      break;
     case 'experiment':
       await commandExperiment(args, config, pricing, t);
       break;