simt-dev 0.3.1 → 0.5.0

package/src/brief/packet.mjs

@@ -0,0 +1,200 @@
+// The brief packet: one document inside a byte ceiling (plan 0003 R27).
+//
+// This module is pure. It reads no filesystem, no environment, no clock and no locale —
+// a packet built twice from the same items is the same bytes, which is the property the
+// accept arm needs and the one a test can check.
+//
+// The packing rule is the kernel's, not a second one invented here: items go to
+// `packToBudget` in the order they should be LOST, and the class marked `hard` is the
+// floor. A brief is not a packet silently cut to size; it is a packet that says, in the
+// packet, what it did not get.
+
+import { packToBudget } from '../kernel/budget.mjs';
+
+/** The ceiling a brief packs to unless it is told otherwise. */
+export const DEFAULT_BRIEF_BYTES = 2048;
+
+/**
+ * The most this tool will ever inject into somebody else's prompt (plan 0003 R29).
+ *
+ * The same number as the default and a different fact: the default is what a packet packs
+ * to, and this is the bar the delivery slice was accepted against. A repository may lower
+ * its own ceiling; it may not raise it past a number that was measured, because a manifest
+ * that could raise it would make an unmeasured figure the promise the tool keeps.
+ */
+export const PROMPT_CAP_BYTES = 2048;
+
+/**
+ * The sections, in the order a reader meets them.
+ *
+ * The order is fixed and identical in every packet. A reader who has to search for the
+ * command is paying the cost the packet exists to remove.
+ */
+const SECTIONS = ['TASK', 'ADVICE', 'COMMANDS', 'FILES', 'TESTS', 'DECISIONS', 'FEDERATION', 'SKILLS', 'LESSONS', 'CAUTIONS'];
+
+/**
+ * What each section is worth when something has to go.
+ *
+ * The numbers are a decision, so they are written here where a reader can argue with
+ * them, rather than spread through the packing code as conditions. They answer one
+ * question: what would a reader rather lose? Cautions they can rediscover, then lessons,
+ * then skill pointers (one command answers all three), then decisions, then tests, then
+ * files. Commands and the task are why the packet exists.
+ *
+ * Federation sits with the decisions, and for the same reason: an external server's answer
+ * names a source a reader can go back to, so losing it costs a question rather than a fact.
+ * A section added later takes a value beside its neighbours rather than renumbering them —
+ * the numbers are a standing answer to "what would a reader rather lose", and a new section
+ * is not a reason to change what an old one is worth.
+ */
+const SECTION_VALUE = {
+  CAUTIONS: 1,
+  // Bench evidence, but advice rather than fact: losing it costs an opinion, not a
+  // command or a path to check (plan 0003 R40).
+  ADVICE: 2,
+  LESSONS: 2,
+  SKILLS: 3,
+  DECISIONS: 4,
+  FEDERATION: 4,
+  TESTS: 5,
+  FILES: 6,
+  COMMANDS: 7,
+  TASK: 8,
+};
+
+/**
+ * The floor. An item marked `hard` is never cut, whatever the ceiling.
+ *
+ * The list is short on purpose: the task itself and the commands that say whether the
+ * change worked. Everything else is recoverable with one more command; these are the ones
+ * whose absence turns the packet into a quiet lie about what the repository needs.
+ */
+const HARD = 'hard';
+const SOFT = 'soft';
+
+/**
+ * A packet under construction.
+ *
+ * Within a section the insertion order IS the relevance order — the packet loses from the
+ * end of a section — so a caller adds the most valuable item first instead of inventing a
+ * score. A number per item would be a second thing to keep consistent with the order, and
+ * the two would drift.
+ */
+export function collect() {
+  const items = [];
+  return {
+    items,
+    /**
+     * Add one line. An empty or non-string line is not added: a blank item is a byte the
+     * packet spends saying nothing.
+     */
+    add(section, text, { hard = false, why = [] } = {}) {
+      if (!SECTIONS.includes(section)) throw new Error(`unknown brief section ${section}`);
+      if (typeof text !== 'string' || text.length === 0) return this;
+      const order = items.length;
+      items.push({ id: String(order), section, text, priority: hard ? HARD : SOFT, order, why });
+      return this;
+    },
+  };
+}
+
+/**
+ * The order items are lost in: least valuable first.
+ *
+ * Between sections by `SECTION_VALUE`; inside a section the last one added goes first.
+ * `hard` items sort to the end, where `packToBudget` refuses to cut them. The order is
+ * made total by the insertion index, because a comparator that returns 0 for two
+ * different items leaves the result to the sort implementation — a determinism hole in a
+ * command whose whole claim is determinism.
+ */
+function cutOrder(items) {
+  const ranked = [...items].sort((a, b) => {
+    if (a.priority !== b.priority) return a.priority === HARD ? 1 : -1;
+    const value = SECTION_VALUE[a.section] - SECTION_VALUE[b.section];
+    if (value !== 0) return value;
+    return b.order - a.order;
+  });
+  return ranked.map(({ id, priority }) => ({ id, priority }));
+}
+
+/**
+ * Render the packet, minus the items that were cut.
+ *
+ * A section with nothing left prints nothing at all, not an empty heading. The `cut` line
+ * is part of the document rather than a footnote, because the reader is the one who has to
+ * decide whether to ask for more — and a packet that shrank without saying so is the
+ * failure this command was written to avoid.
+ */
+function renderPacket(items, { cut = new Set(), budget = DEFAULT_BRIEF_BYTES } = {}) {
+  const lines = [];
+  for (const section of SECTIONS) {
+    const kept = items.filter((item) => item.section === section && !cut.has(item.id));
+    if (kept.length === 0) continue;
+    lines.push(section);
+    for (const item of kept) for (const line of item.text.split('\n')) lines.push(`  ${line}`);
+  }
+  const lost = items.filter((item) => cut.has(item.id));
+  if (lost.length > 0) {
+    const where = SECTIONS.filter((section) => lost.some((item) => item.section === section)).map(
+      (section) => `${section.toLowerCase()} ${lost.filter((item) => item.section === section).length}`,
+    );
+    lines.push(`cut ${lost.length} of ${items.length} items to fit ${budget}: ${where.join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+/** The byte length of a rendering. The ceiling is measured in these, not in characters. */
+function packetBytes(items, { cut = new Set(), budget = DEFAULT_BRIEF_BYTES } = {}) {
+  return Buffer.byteLength(renderPacket(items, { cut, budget }));
+}
+
+/**
+ * Pack the items into a packet.
+ *
+ * Returns the text, the byte count before and after, and whether the floor itself is over
+ * the line. `floorHeld` is reported to the caller rather than printed: it is the one fact
+ * the packet cannot state about itself without the statement changing the thing it
+ * describes, so it belongs to `--explain` and the JSON payload.
+ *
+ * A budget of 0 means no ceiling at all — the reader asked for the whole packet — and the
+ * packing step is skipped rather than run against a number that means "unlimited".
+ */
+export function buildPacket(items, { budget = DEFAULT_BRIEF_BYTES } = {}) {
+  const before = packetBytes(items, { budget });
+  if (!(budget > 0)) {
+    return { cut: [], before, after: before, floorHeld: false, text: renderPacket(items, { budget }) };
+  }
+  const result = packToBudget({
+    candidates: cutOrder(items),
+    ceiling: budget,
+    costs: (cut) => packetBytes(items, { cut: new Set(cut), budget }),
+  });
+  const cut = new Set(result.cut);
+  return { ...result, text: renderPacket(items, { cut, budget }) };
+}
+
+/**
+ * One line per item, for `--explain`: what was kept, what was cut, and the two facts that
+ * decided it.
+ *
+ * The explanation is not part of the packet and is never measured against the ceiling —
+ * it exists so a reader can tell a packet that is complete from one that was trimmed,
+ * which is the question the packet's own byte count cannot answer for them.
+ */
+export function explainPacket(items, { cut = new Set() } = {}) {
+  const counts = new Map();
+  for (const item of items) counts.set(item.section, (counts.get(item.section) ?? 0) + 1);
+  const seen = new Map();
+  const lines = [];
+  for (const item of items) {
+    const position = (seen.get(item.section) ?? 0) + 1;
+    seen.set(item.section, position);
+    const verdict = cut.has(item.id) ? 'cut' : 'keep';
+    const reason = item.why.length > 0 ? item.why.join('; ') : 'carried by its section';
+    lines.push(
+      `${verdict} ${item.section} ${position}/${counts.get(item.section)} worth ${SECTION_VALUE[item.section]}: ${item.text.split('\n')[0]}`,
+    );
+    lines.push(`     ${reason}`);
+  }
+  return lines;
+}

package/src/commands/agenthook.mjs

@@ -11,6 +11,12 @@
 // walks the repository. A hook that measured the tree before answering would be exactly
 // the latency the plan's acceptance criterion exists to prevent.
 //
+// A second event, `prompt-submit`, delivers rather than decides: it needs the manifest,
+// the index and the packet assembly, so it is reached through a dynamic `import()` that
+// only that event takes. A tool call therefore still pays for nothing that walks the
+// repository, and the one path that does pays for it once per prompt instead of once per
+// command.
+//
 // A denial exits 2, which is what every harness in the table reads as "block". A mistake
 // in the hook's own invocation must NOT exit 2: a typo in a config would then block every
 // tool call. Failures of this command exit 1, which a harness reports as a failed hook,
@@ -60,6 +66,32 @@ export async function agentHookCommand(args, flags) {
     return EXIT.OK;
   }
 
+  // Delivery, not decision: the packet goes into the prompt and the exit code stays 0
+  // whatever happens. The module behind it is the one thing here that reads the
+  // repository, and the tool-call path above must not pay for it, so the door is a
+  // dynamic import that only this event opens.
+  if (event === 'prompt-submit') {
+    const { deliverPrompt } = await import('../agenthooks/prompt.mjs');
+    const delivered = await deliverPrompt(row, payload);
+    if (delivered.skipped) {
+      note(`note     ${id}: no packet delivered (${delivered.skipped})`);
+      return EXIT.OK;
+    }
+    emit(JSON.stringify(delivered.json));
+    return EXIT.OK;
+  }
+
+  if (event === 'post-tool-use') {
+    const { deliverLessonRecall } = await import('../memory/lessons.mjs');
+    const recalled = await deliverLessonRecall(row, payload, { root: flags.root });
+    if (recalled.skipped) {
+      note(`note     ${id}: no lesson recalled (${recalled.skipped})`);
+      return EXIT.OK;
+    }
+    emit(JSON.stringify(recalled.json));
+    return EXIT.OK;
+  }
+
   const { root, command, writes } = factsFrom(row, payload);
   const facts = await factsFor(root, { command, writes });
   const decision = decide({ event, facts, env: process.env });
@@ -77,6 +109,22 @@ export async function agentHookCommand(args, flags) {
   const json = decisionJson(row, decision);
   if (json === null) return EXIT.OK;
 
+  if (root) {
+    try {
+      const { recordHookDenial } = await import('../memory/lessons.mjs');
+      await recordHookDenial(root, {
+        harness: row.id,
+        event,
+        policies: decision.blocked,
+        messages: decision.messages,
+        command,
+        writes,
+      });
+    } catch {
+      // Recording a lesson candidate must never block or alter the hook decision.
+    }
+  }
+
   emit(JSON.stringify(json));
   for (const message of decision.messages) note(`blocked  ${message}`);
   return row.denyExit;
@@ -91,14 +139,37 @@ export async function agentHooksCommand(sub, args, flags) {
 
 async function installHooks(root, flags) {
   const mode = writeMode(flags);
+  // The delivery is a second entry in the same config, and a repository asks for it by
+  // declaring a `brief` key rather than by having the entry. Read through a dynamic
+  // import for the same reason the hook delivers through one.
+  const { promptOptIn } = await import('../agenthooks/prompt.mjs');
+  const { listPromotedLessons } = await import('../memory/lessons.mjs');
+  const [optIn, promotedLessons] = await Promise.all([
+    promptOptIn(root),
+    listPromotedLessons(root).catch(() => []),
+  ]);
+  const hasLessons = promotedLessons.length > 0;
   const plan = [];
   for (const row of adapters()) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
-    const result = rendered(row, existing);
-    plan.push({ id: row.id, path, action: result.error ? 'refused' : result.action, error: result.error, text: result.text });
+    const result = rendered(row, existing, { prompt: optIn.optedIn, post: hasLessons });
+    plan.push({
+      id: row.id,
+      path,
+      action: result.error ? 'refused' : result.action,
+      error: result.error,
+      text: result.text,
+      prompt: row.prompt === null || row.prompt === undefined ? null : optIn.optedIn ? 'declared' : 'not declared',
+    });
   }
 
+  // One line for the repository, not one per adapter: the opt-in is a property of the
+  // repository, and someone who has not declared it is told how once.
+  const promptLine = plan.some((p) => p.prompt !== null) && !optIn.optedIn
+    ? [`PROMPT   not opted in (${optIn.why}); add "brief": {} to the manifest to deliver the packet on every prompt`]
+    : [];
+
   // The readers this tool does not write an entry for, reported rather than skipped in
   // silence: a command that writes four files and says nothing about the fifth harness
   // in the repository reads as "that one is covered too".
@@ -128,6 +199,7 @@ async function installHooks(root, flags) {
         `repo     ${root}`,
         ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}${p.error ? `  (${p.error})` : ''}`),
         ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+        ...promptLine,
         '',
         refused.length > 0
           ? `REFUSED  ${refused.length} config file(s) could not be read; nothing written`
@@ -177,6 +249,7 @@ async function installHooks(root, flags) {
       `repo     ${root}`,
       ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
       ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+      ...promptLine,
       '',
       `WROTE    ${written.length} hooks file(s); each one runs ${CLI} agent-hook before the tool call`,
     ].join('\n'),
@@ -196,14 +269,14 @@ async function hooksStatus(root, flags) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
     if (existing === null) {
-      rows.push({ id: row.id, path, state: 'absent', entries: 0, note: null });
+      rows.push({ id: row.id, path, state: 'absent', entries: 0, prompt: row.prompt ? 'absent' : null, note: null });
       continue;
     }
     let config;
     try {
       config = JSON.parse(existing);
     } catch (e) {
-      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, note: e.message });
+      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, prompt: row.prompt ? 'unknown' : null, note: e.message });
       problems.push(`${path} is not valid JSON: ${e.message}`);
       continue;
     }
@@ -211,16 +284,18 @@ async function hooksStatus(root, flags) {
     // refuses to write into one. Status has to agree with it, or one question gets two
     // answers and the quiet one is the one a reader acts on.
     if (config === null || typeof config !== 'object' || Array.isArray(config)) {
-      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, note: 'not a JSON object' });
+      rows.push({ id: row.id, path, state: 'unreadable', entries: 0, prompt: row.prompt ? 'unknown' : null, note: 'not a JSON object' });
       problems.push(`${path} is not a JSON object, so this tool will not write into it`);
       continue;
     }
     const found = installedIn(row, config).length;
+    const prompts = row.prompt ? installedIn(row, config, EVENTS[1]).length : 0;
     rows.push({
       id: row.id,
       path,
       state: found > 0 ? 'present' : 'absent',
       entries: found,
+      prompt: row.prompt ? (prompts > 0 ? 'present' : 'absent') : null,
       note: found > 0 ? (row.trust ?? null) : null,
     });
   }
@@ -243,6 +318,10 @@ async function hooksStatus(root, flags) {
     const state = { present: 'PRESENT ', absent: 'ABSENT  ', unreadable: 'INVALID ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
     lines.push(`${state} ${r.id.padEnd(12)} ${r.path ?? '(no hooks file is documented)'}`);
     if (r.state === 'absent') lines.push(`          ${' '.repeat(12)} install: ${CLI} agent-hooks install --yes`);
+    // The second event is a separate answer to a separate question: a harness can carry
+    // the tool hook and not the delivery, and a reader who is told "PRESENT" would
+    // otherwise conclude the packet arrives on every prompt.
+    if (r.prompt) lines.push(`          ${' '.repeat(12)} prompt-submit: ${r.prompt}`);
     if (r.note) lines.push(`          ${' '.repeat(12)} ${r.note}`);
   }
   if (problems.length > 0) {

package/src/commands/bench.mjs

@@ -15,6 +15,8 @@ import { buildBenchReport } from '../bench/report.mjs';
 import { formatRecall, measureRecall } from '../index/map.mjs';
 import { ablateBench } from '../bench/ablate.mjs';
 import { runBenchProbes } from '../bench/probes.mjs';
+import { selectRuleVariants } from '../bench/variants.mjs';
+import { criticBench } from '../review/critic.mjs';
 import { listFlag } from './skills.mjs';
 
 export async function benchMineCommand(positional, flags) {
@@ -280,16 +282,8 @@ export async function benchAblateCommand(positional, flags) {
     emitJson({
       ok: true,
       command: 'bench ablate',
-      root: result.root,
       dryRun,
-      applied: result.applied,
-      pricesLoaded: result.pricesLoaded,
-      canarySize: result.canarySize,
-      canaryTasks: result.canaryTasks,
-      totalTasks: result.totalTasks,
-      sections: result.sections,
-      ranking: result.ranking,
-      deletionCandidates: result.deletionCandidates,
+      ...result,
     });
     return EXIT.OK;
   }
@@ -340,13 +334,8 @@ export async function benchProbesCommand(positional, flags) {
     emitJson({
       ok: true,
       command: 'bench probes',
-      root: result.root,
       dryRun,
-      applied: result.applied,
-      probeCount: result.probeCount,
-      probes: result.probes,
-      arms: result.arms,
-      runs: result.runs,
+      ...result,
     });
     return EXIT.OK;
   }
@@ -367,5 +356,73 @@ export async function benchProbesCommand(positional, flags) {
   return EXIT.OK;
 }
 
+export async function benchVariantsCommand(positional, flags) {
+  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const { dryRun, apply } = writeMode(flags);
+  let result;
+  try {
+    result = await selectRuleVariants(root, {
+      apply,
+      harness: flags.harness ?? 'gold',
+      model: flags.model,
+      reps: flags.reps ?? 1,
+      includeAll: flags.all === true,
+    });
+  } catch (error) {
+    return fail(
+      `${root}: ${error.message ?? error}`,
+      EXIT.CONFIG,
+      `mine tasks first with \`${CLI} bench mine --yes\` and rerun \`${CLI} bench variants --yes\``,
+    );
+  }
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'bench variants', dryRun, ...result });
+    return EXIT.OK;
+  }
+  const lines = [
+    `bench    variants  ${result.root}`,
+    `mode     ${result.applied ? 'applied' : dryRun ? 'dry-run (writes nothing)' : 'preview / stored runs (pass --yes to execute canary and lock winners)'}`,
+    `harness  ${result.harness}  model=${result.model}`,
+    `slots    ${result.slots.length}  (canary: ${result.canaryTasks}/${result.totalTasks} tasks)`,
+    ...result.slots.map(
+      (s) => `slot     ${s.slotId}  status=${s.status}  winner=${s.winner}  dR=${s.dR}  dC=${s.dC}  n=${s.n}  p=${s.p}`,
+    ),
+  ];
+  if (!result.applied) lines.push(`remedy   run: ${CLI} bench variants --yes`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+
+
 
+// `simt bench critic` (plan 0003 R39).
+//
+// The row's acceptance measured, or reported missing rather than inferred: the
+// critic runs over a labelled set of historical diffs and the bench reports
+// precision and recall for the BLOCK binary. The metric never gates the critic —
+// the row says precision >= 0.8 on >= 30 labelled diffs promotes it to a gate,
+// and until a bench here shows that, every report calls the critic advisory.
+export async function benchCriticCommand(positional, flags, commands = []) {
+  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const labelsPath = flags.labels ?? '.simt-dev/critic-labels.jsonl';
+  const result = await criticBench(root, { labelsPath, flags, commands });
+  if (typeof result === 'number') return result;
 
+  if (isJson(flags)) {
+    emitJson(result, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [
+    `bench    critic  ${root}`,
+    `labels   ${result.labels} (${labelsPath})  measured ${result.measured}  errors ${result.errors.length}`,
+    `counts   tp=${result.tp} fp=${result.fp} fn=${result.fn} tn=${result.tn}`,
+    `precision ${result.precision === null ? 'unmeasured' : result.precision.toFixed(3)}`,
+    `recall    ${result.recall === null ? 'unmeasured' : result.recall.toFixed(3)}`,
+    `gated    ${result.gated ? 'yes' : 'no'}`,
+  ];
+  if (result.labelsNote) lines.push(`labels   ${result.labelsNote}`);
+  for (const error of result.errors) lines.push(`error    ${error}`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/brief.mjs

@@ -0,0 +1,78 @@
+// `simt brief "<task>"` — print the packet (plan 0003 R27).
+//
+// What this is for: an agent that has to explore a repository to find out how to run its
+// tests, which files the task will touch and what governs them spends turns discovering
+// what the repository already knows. The packet is that answer, assembled from the index
+// the repository already has, in the bytes a prompt can carry.
+//
+// The assembly itself is in `../brief/assemble.mjs`, because three doors open onto it —
+// this command, MCP's `brief` tool and the prompt-submit hook — and one implementation
+// behind three doors is the only way the three cannot disagree. This file owns the
+// command line: what a task may be, what the ceiling may be, and how the packet is
+// rendered for a terminal or for `--json`.
+//
+// One thing is deliberately missing: `skills brief` keeps its own behaviour, and MCP's
+// `skills_brief` keeps its own shape. Superseding them changes two accepted decisions
+// (ADR-035, ADR-052) and the MCP contract, and this slice carries no ADR to do it.
+
+import { CLI } from '../name.mjs';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { DEFAULT_BRIEF_BYTES, explainPacket } from '../brief/packet.mjs';
+import { assembleBrief } from '../brief/assemble.mjs';
+
+export async function briefCommand(args, flags) {
+  if (args.length > 1) {
+    return fail(`brief takes one task, not ${args.length}`, EXIT.USAGE, `run: ${CLI} brief "<task>"`);
+  }
+  if (args.length === 1 && flags.task !== undefined) {
+    return fail('the task was passed twice, as an argument and as --task', EXIT.USAGE, `run: ${CLI} brief "<task>"`);
+  }
+  const budget = flags.budget === undefined ? DEFAULT_BRIEF_BYTES : Number(flags.budget);
+  if (!Number.isInteger(budget) || budget < 0) {
+    return fail(`--budget must be a byte count, not ${flags.budget}`, EXIT.USAGE, `run: ${CLI} brief --budget ${DEFAULT_BRIEF_BYTES}`);
+  }
+
+  const result = await assembleBrief({
+    root: flags.root ?? process.cwd(),
+    task: String(args[0] ?? flags.task ?? ''),
+    paths: flags.paths === undefined ? null : flags.paths,
+    budget,
+    flags,
+  });
+  if (result.error) return result.error;
+  // Unreachable from here — only a delivered brief asks for a cold index to be reported
+  // rather than built — but a silent empty packet would be the worst way to find out.
+  if (result.cold) {
+    return fail('the index is empty, and this command will not assemble a packet from it', EXIT.UNSUPPORTED, `run ${CLI} index`);
+  }
+  const { root, kind, basis, task, scope, budget: ceiling, items, packed, sections } = result;
+  const cut = new Set(packed.cut);
+
+  if (isJson(flags)) {
+    emitJson(
+      {
+        ok: true,
+        command: 'brief',
+        root,
+        kind,
+        basis,
+        task,
+        scope,
+        budget: ceiling,
+        bytes: packed.after,
+        before: packed.before,
+        floorHeld: packed.floorHeld,
+        cut: packed.cut,
+        sections,
+        explain: flags.explain === true ? explainPacket(items, { cut }) : undefined,
+        text: packed.text,
+      },
+      { pretty: flags.pretty === true, maxBytes: Number(flags.maxBytes ?? 0) || 0 },
+    );
+    return EXIT.OK;
+  }
+
+  const body = flags.explain === true ? [packed.text, '', 'EXPLAIN', ...explainPacket(items, { cut })] : [packed.text];
+  emit(body.join('\n'), { maxBytes: Number(flags.maxBytes ?? 0) || 0 });
+  return EXIT.OK;
+}

package/src/commands/compare.mjs

@@ -26,6 +26,7 @@ import { provenanceDigest } from '../projection/project.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { buildRow, summarise } from '../compare/row.mjs';
 import { discover } from '../compare/discover.mjs';
+import { learnAcrossEstate, renderLearningLines } from '../compare/learn.mjs';
 import { targetRoot, WORKSPACE_REMEDY } from '../workspace.mjs';
 
 /** Gate kinds, so a row can tell a command gate with no command from a script gate. */
@@ -65,6 +66,7 @@ export async function compareCommand(positional, flags) {
   // bound. Determinism of the output matters more than wall clock on a dashboard.
   const rows = [];
   for (const repo of found.repos) rows.push(await buildRow(repo, context));
+  const learning = await learnAcrossEstate(found.repos);
 
   const summary = summarise(rows, {
     root,
@@ -106,6 +108,7 @@ export async function compareCommand(positional, flags) {
         shas: summary.shas,
       },
       rows,
+      learning,
       worktrees: found.worktrees.map((w) => ({
         name: w.name,
         path: w.path,
@@ -117,7 +120,7 @@ export async function compareCommand(positional, flags) {
     return rows.some((r) => r.problems.length > 0) ? EXIT.FAIL : EXIT.OK;
   }
 
-  emit(render(rows, summary, found), { maxBytes: flags.maxBytes ?? 0 });
+  emit(render(rows, summary, found, learning), { maxBytes: flags.maxBytes ?? 0 });
   if (summary.shape === 'repo') {
     note('note     one repository compared; pass --root at a workspace directory to compare its siblings');
   } else if (target.source === 'none') {
@@ -146,7 +149,7 @@ export async function compareCommand(positional, flags) {
  * the longest value, and an agent cannot tell which column is which without
  * counting spaces.
  */
-function render(rows, summary, found) {
+function render(rows, summary, found, learning = null) {
   const lines = [
     // `workspace` and `repo` are the same field with different names, and the name is the
     // honest one: a reader who sees "workspace" and gets one repo was told a lie. `root`
@@ -204,6 +207,11 @@ function render(rows, summary, found) {
     lines.push('');
   }
 
+  const learningLines = renderLearningLines(learning);
+  if (learningLines.length > 0) {
+    lines.push(...learningLines, '');
+  }
+
   return lines.join('\n').trimEnd();
 }