@supersuit/hyperspec 0.6.0 → 0.8.0

package/src/judges/lineup.mjs

@@ -0,0 +1,272 @@
+// The lineup: a blind test of voice. Up to three goldens from the spec's DNA scope (passages a
+// person approved as this writer, in this scope) go in a lineup with one passage of the draft,
+// shuffled and labelled; a judge who can pick the draft's passage out has found that the draft does
+// not yet sound like the writer. The station passes when the judge picks a golden.
+//
+// Every candidate is built the same way, so none can be told apart by its formatting:
+// ONE prose paragraph (proseParagraphs below), reflowed to a single line. The target length is the
+// median, in characters, of every prose paragraph of every golden in the scope. Each of the scope's
+// first three goldens with a prose paragraph (by file name, the order src/dna.mjs's reader returns
+// them in) contributes its paragraph closest to that target; the draft contributes its paragraph
+// closest to the same target, skipping any that is already a golden paragraph word for word
+//, since a lineup of two identical passages tests nothing. Ties go to the earliest.
+//
+// The shuffle is seeded from the draft's full text (lineupSeed below), so the same draft always gets
+// the same labels and a revised draft gets a fresh draw. The seed is never a value the packet
+// carries: the packet holds the draft's hash and one paragraph of it, and a seed taken from the
+// hash would let anyone holding the packet rerun the shuffle and read off the answer. The draft's
+// label is the hidden answer: it goes only in the station's key, which prepare writes to
+// lineup.key.json for a person to read and record rebuilds rather than reading.
+
+import { resolve } from "node:path";
+import { sha256 } from "../hash.mjs";
+import { str } from "../placeholder.mjs";
+import { readScope } from "../dna.mjs";
+import { splitLines } from "../draft.mjs";
+
+export const name = "lineup";
+
+export const MAX_GOLDENS = 3;
+export const LABELS = Object.freeze(["A", "B", "C", "D"]);
+
+export const LINEUP_INSTRUCTIONS = [
+  "Each passage in inputs.candidates carries a capital-letter label.",
+  "All but one were written by the writer of inputs.scope, for this form, audience and purpose, and approved by a person; exactly one comes from a new draft.",
+  "Pick the label of the passage you believe comes from the new draft, judging by voice alone: rhythm, diction, sentence shape, what this writer would and would not say.",
+  "Give your confidence from 0 (a guess) to 1 (certain), and in reason say what in the candidates decided it.",
+  "Judge from the packet's inputs alone: do not open the spec, the draft or any other file the packet names.",
+  "Answer only in the verdict shape given in verdict_schema.",
+].join(" ");
+
+const isObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const chars = (s) => [...s].length;
+
+// ---- the draft's prose paragraphs ----------------------------------------------------------------
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+const HEADING = /^ {0,3}#{1,6}(?:[ \t]|$)/;
+// A line that makes its block something other than a prose paragraph: a list item, a blockquote, a
+// table row, a thematic break or setext underline (front matter's --- too), or an HTML line.
+const NOT_PROSE = [
+  /^ {0,3}(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/,
+  /^ {0,3}>/,
+  /^\s*\|/,
+  /^ {0,3}(?:(?:[-*_][ \t]*){3,}|=+[ \t]*)$/,
+  /^ {0,3}<[A-Za-z/!?]/,
+];
+const INDENTED_CODE = /^(?: {4}|\t)/;
+
+// proseParagraphs(text): [{ line, text }] for every prose paragraph of a markdown draft, in order.
+// A block is a run of non-blank lines; fenced code (blank lines inside it included) and ATX headings
+// end a block and are never part of one. A block is prose only when every one of its lines is plain
+// text: a block holding a list item, a quotation, a table row, a break or HTML is left out whole
+// (a paragraph that runs into a list is not a passage a golden could stand beside), and so is a
+// block opening with indented code. text is the block's lines, trailing whitespace trimmed, joined
+// with "\n"; line is the 1-based draft line it starts on.
+export function proseParagraphs(text) {
+  const lines = splitLines(String(text));
+  const out = [];
+  let block = [];
+  let fence = null;
+  const flush = () => {
+    if (block.length && !INDENTED_CODE.test(block[0].text) && block.every((l) => !NOT_PROSE.some((re) => re.test(l.text)))) {
+      out.push({ line: block[0].line, text: block.map((l) => l.text.trimEnd()).join("\n") });
+    }
+    block = [];
+  };
+  lines.forEach((raw, i) => {
+    const m = raw.match(FENCE);
+    if (fence) {
+      if (m && m[1][0] === fence[0] && m[1].length >= fence.length && !raw.slice(m[0].length).trim()) fence = null;
+      return;
+    }
+    if (m) { flush(); fence = m[1]; return; }
+    if (!raw.trim() || HEADING.test(raw)) { flush(); return; }
+    block.push({ line: i + 1, text: raw });
+  });
+  flush();
+  return out;
+}
+
+function median(values) {
+  const s = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+
+// reflow(text): the paragraph on one line, every run of whitespace (line breaks included) collapsed
+// to one space. Lineup carries no evidence, so nothing in a candidate has to stay verbatim.
+export const reflow = (text) => String(text).replace(/\s+/g, " ").trim();
+
+// pickPassage(paragraphs, lengths, { exclude }): the paragraph whose length in characters is
+// closest to the median of `lengths`; on a tie, the earliest. A paragraph whose text is in
+// `exclude` (a Set) is never picked. null when no paragraph is left.
+export function pickPassage(paragraphs, lengths, { exclude } = {}) {
+  const target = median(lengths);
+  let best = null;
+  let bestDistance = Infinity;
+  for (const p of paragraphs) {
+    if (exclude?.has(p.text)) continue;
+    const d = Math.abs(chars(p.text) - target);
+    if (d < bestDistance) { best = p; bestDistance = d; }
+  }
+  return best;
+}
+
+// ---- the shuffle ---------------------------------------------------------------------------------
+
+// mulberry32: a small, well-mixed 32-bit PRNG, so the shuffle needs no dependency and gives the
+// same sequence on every Node version.
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// seededShuffle(items, sha256Hex): a new array, items in a Fisher-Yates order drawn from a PRNG
+// seeded with the first 32 bits of the hash. The same items and hash always give the same order.
+export function seededShuffle(items, sha256Hex) {
+  const random = mulberry32(parseInt(String(sha256Hex).slice(0, 8), 16) || 0);
+  const out = [...items];
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1));
+    [out[i], out[j]] = [out[j], out[i]];
+  }
+  return out;
+}
+
+// lineupSeed(draftText): the hash the shuffle is seeded with. It is taken from the draft's whole
+// text under a fixed prefix, never from draft_sha256 or anything else the packet carries, since the
+// packet does not carry the draft's text: a judge holding only the packet cannot recompute the
+// order, while the same draft always gets the same labels.
+export const LINEUP_SEED_PREFIX = "hyperspec lineup seed\n";
+export const lineupSeed = (draftText) => sha256(LINEUP_SEED_PREFIX + String(draftText));
+
+// ---- the station ---------------------------------------------------------------------------------
+
+// Every prose paragraph of a text, reflowed to one line: [{ line, text }].
+const reflowedParagraphs = (text) => proseParagraphs(text).map((p) => ({ line: p.line, text: reflow(p.text) }));
+
+// What the lineup would hold for this spec and draft, or why it cannot be built: { skip } or
+// { scope, goldens: [{ source, text }], passage: { line, text } }. The one plan both skipReason and
+// packet read, so a station that applies always has a packet to build. Without a draft (never the
+// case from prepare or record) only the scope's half is checked.
+function lineupPlan(spec, draft) {
+  const dna = spec.data?.writing?.dna;
+  if (!isObject(dna)) return { skip: "writing.dna is not written (deferred)" };
+  const scopeDir = str(dna.scope_dir);
+  if (!scopeDir) return { skip: "writing.dna.scope_dir is not set" };
+  if (!str(dna.check?.rubric)) return { skip: "writing.dna.check has no rubric" };
+
+  const disk = readScope(resolve(spec.dir || ".", scopeDir), { displayDir: scopeDir });
+  if (disk.findings.some((x) => x.id === "writing-dna-goldens-missing" || x.id === "writing-dna-goldens-outside")) {
+    return { skip: `writing.dna.scope_dir "${scopeDir}": its goldens cannot be read (run \`hyperspec lint\` for details)`, fromSources: true };
+  }
+  const read = disk.goldens.filter((g) => g.text).map((g) => ({ source: g.path, paragraphs: reflowedParagraphs(g.text) }));
+  if (!read.length) return { skip: `writing.dna.scope_dir "${scopeDir}" has no goldens`, fromSources: true };
+  const withProse = read.filter((g) => g.paragraphs.length);
+  if (!withProse.length) return { skip: `writing.dna.scope_dir "${scopeDir}" has no golden with a prose paragraph`, fromSources: true };
+
+  const all = withProse.flatMap((g) => g.paragraphs);
+  const lengths = all.map((p) => chars(p.text));
+  const goldens = withProse.slice(0, MAX_GOLDENS).map((g) => ({ source: g.source, text: pickPassage(g.paragraphs, lengths).text }));
+  if (!draft) return { scope: disk.scope, goldens, passage: null };
+
+  const drafted = reflowedParagraphs(draft.text);
+  if (!drafted.length) return { skip: "the draft has no prose paragraph to put in the lineup" };
+  const passage = pickPassage(drafted, lengths, { exclude: new Set(all.map((p) => p.text)) });
+  if (!passage) return { skip: "every prose paragraph of the draft is already a golden in the scope, word for word", fromSources: true };
+  // A draft that is nothing but this paragraph would give the answer away: the packet carries the
+  // draft's hash, and the candidate's text (with or without a line break) is the whole draft.
+  if (reflow(draft.text) === passage.text) return { skip: "the draft is one paragraph, the passage the lineup would show, so the packet's draft_sha256 could identify it" };
+  return { scope: disk.scope, goldens, passage };
+}
+
+// null when the lineup applies, otherwise why not: it needs a written dna block whose scope_dir is
+// set and whose check names a rubric, a golden with a prose paragraph in that scope, and a prose
+// paragraph in the draft that is not already a golden and is not the whole draft.
+export function skipReason(spec, draft) {
+  return lineupPlan(spec, draft).skip ?? null;
+}
+
+// The skip reason when lineup skips because of its goldens (unreadable, none, none with prose, or
+// every draft paragraph already one of them), else null: record calls such a packet stale rather
+// than altered.
+export function sourceSkip(spec, draft) {
+  const p = lineupPlan(spec, draft);
+  return p.fromSources ? p.skip : null;
+}
+
+// Where the lineup's inputs come from beyond the spec and the draft: record names them when the
+// packet's inputs no longer match while neither hash changed.
+export function inputSources(spec) {
+  const dir = str(spec.data?.writing?.dna?.scope_dir);
+  return dir ? `the DNA scope (${dir}: scope.md and goldens)` : null;
+}
+
+// The packet's rubric (dna.check.rubric, verbatim), inputs (the scope and the labelled candidates,
+// text only) and verdict schema, and the key: which label is the draft's, and where every
+// candidate came from.
+export function packet(spec, draft) {
+  const { scope, goldens, passage } = lineupPlan(spec, draft);
+  const pool = [...goldens, { source: "draft", text: passage.text }];
+  const order = seededShuffle(pool, lineupSeed(draft.text));
+  const labels = LABELS.slice(0, order.length);
+  return {
+    rubric: spec.data.writing.dna.check.rubric,
+    inputs: {
+      scope: { writer: str(scope?.writer), form: str(scope?.form), audience: str(scope?.audience), purpose: str(scope?.purpose) },
+      candidates: order.map((c, i) => ({ label: labels[i], text: c.text })),
+    },
+    verdict_schema: {
+      type: "object",
+      required: ["pick", "confidence", "reason"],
+      properties: {
+        pick: { enum: labels, description: "the label of the passage you believe comes from the new draft" },
+        confidence: { type: "number", minimum: 0, maximum: 1 },
+        reason: { type: "string", description: "what in the candidates decided the pick" },
+      },
+    },
+    key: {
+      station: name,
+      draft_label: labels[order.findIndex((c) => c.source === "draft")],
+      draft_line: passage.line,
+      candidates: order.map((c, i) => ({ label: labels[i], source: c.source })),
+    },
+  };
+}
+
+// Every problem with the verdict, as findings. The reason describes the candidates rather than
+// quoting the draft, so it carries no evidence.
+export function validate(verdict, pkt, t) {
+  if (!isObject(verdict)) return [t.shape("the verdict is not a JSON object", "Write one object: { pick, confidence, reason }.")];
+  const out = [];
+  const labels = pkt.inputs.candidates.map((c) => c.label);
+  if (typeof verdict.pick !== "string") out.push(t.shape("pick is missing or not a string", `Set pick to one candidate's label: ${labels.join(", ")}.`));
+  else if (!labels.includes(verdict.pick)) out.push(t.finding("judge-lineup-pick-unknown", `pick "${verdict.pick}" is not a label in the lineup`, `Pick one of the labels: ${labels.join(", ")}.`));
+  if (typeof verdict.confidence !== "number" || !Number.isFinite(verdict.confidence) || verdict.confidence < 0 || verdict.confidence > 1) {
+    out.push(t.shape("confidence is missing or not a number from 0 to 1", "Set confidence to a number from 0 (a guess) to 1 (certain)."));
+  }
+  if (typeof verdict.reason !== "string" || !verdict.reason.trim()) out.push(t.shape("reason is missing or empty", "Say what in the candidates decided the pick."));
+  return out;
+}
+
+// Passes when the pick is a golden: the judge could not tell the draft from the writer.
+export function derive(verdict, pkt, t, key) {
+  if (verdict.pick !== key.draft_label) return { status: "pass", findings: [] };
+  const n = pkt.inputs.candidates.length;
+  return {
+    status: "fail",
+    findings: [t.finding(
+      "judge-lineup-picked",
+      `the judge picked the draft's passage (${verdict.pick}) out of ${n} candidates with confidence ${verdict.confidence}: ${verdict.reason.trim()}`,
+      "Revise this passage toward the goldens' voice, where the reason points; if the goldens do not cover this kind of passage, add one that does. Then prepare and judge again.",
+      key.draft_line,
+    )],
+  };
+}

package/src/judges/persona.mjs

@@ -0,0 +1,137 @@
+// The persona: a judge reads the draft as the persona block describes its speaker (who they are,
+// their stance, what they may assert and what they will not say) against the claims ledger, the
+// closed list of facts the draft may state, and reports every place the voice breaks. hyperspec
+// writes the packet, checks every quoted span against the draft (src/judge.mjs's evidence rule) and
+// derives the status: pass when there is no break.
+//
+// The claims are the texts of the ledger the claims station reads (writing.sources.ledger, through
+// its readClaimsLedger), so both stations see the same claims. That file is neither the spec nor the
+// draft, so the station names it in inputSources: a ledger changed after prepare makes the packet
+// stale, not altered. With no ledger declared (writing.sources deferred) the claims are null, the
+// instructions say facts cannot be checked against sources, and a break of kind unsourced_fact is
+// an invalid verdict: an empty list would read as "no fact is sourced". A ledger
+// declared but unreadable skips the station, for the same reason.
+
+import { str } from "../placeholder.mjs";
+import { readClaimsLedger } from "../stations/claims.mjs";
+
+export const name = "persona";
+
+// The four ways a persona breaks, a closed set, in the order the verdict schema lists them.
+export const PERSONA_KINDS = Object.freeze(["stance", "assertion", "will_not_say", "unsourced_fact"]);
+
+export const PERSONA_INSTRUCTIONS = [
+  "Read inputs.draft as the speaker inputs.persona describes.",
+  "Report every break as an entry in breaks: the passage as evidence, copied verbatim from inputs.draft, at least three whole words; its kind; and why.",
+  "The kind is one of: stance (the voice leaves inputs.persona.stance), assertion (it asserts something outside inputs.persona.may_assert), will_not_say (it says something inputs.persona.will_not_say rules out), unsourced_fact (it states a fact that none of inputs.claims holds).",
+  "When inputs.claims is null, no claims ledger is declared and facts cannot be checked against sources: do not report unsourced_fact.",
+  "If the voice holds throughout, breaks is an empty list.",
+  "Answer only in the verdict shape given in verdict_schema.",
+].join(" ");
+
+const isObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const texts = (v) => (Array.isArray(v) ? v.map(str).filter(Boolean) : []);
+const nonEmpty = (v) => typeof v === "string" && v.trim().length > 0;
+
+// null when the persona applies: a written persona block whose check names a rubric, and a claims
+// ledger that is either not declared or readable.
+export function skipReason(spec) {
+  const persona = spec.data?.writing?.persona;
+  if (!isObject(persona)) return "writing.persona is not written (deferred)";
+  if (!str(persona.check?.rubric)) return "writing.persona.check has no rubric";
+  const ledger = readClaimsLedger(spec);
+  if (ledger.missing) return ledgerSkip(ledger.path);
+  return null;
+}
+
+const ledgerSkip = (path) => `writing.sources.ledger "${path}" cannot be read (run \`hyperspec check\` for details)`;
+
+// The skip reason when the station skips because of its source file (the claims ledger cannot be
+// read), else null: record calls such a packet stale rather than altered.
+export function sourceSkip(spec) {
+  const persona = spec.data?.writing?.persona;
+  if (!isObject(persona) || !str(persona.check?.rubric)) return null;
+  const ledger = readClaimsLedger(spec);
+  return ledger.missing ? ledgerSkip(ledger.path) : null;
+}
+
+// The file besides the spec and the draft this station's inputs come from, or null when there is none.
+export function inputSources(spec) {
+  const path = readClaimsLedger(spec).path;
+  return path ? `the claims ledger (${path})` : null;
+}
+
+// The packet's rubric (persona.check.rubric, verbatim), inputs and verdict schema. No answer key.
+export function packet(spec, draft) {
+  const p = spec.data.writing.persona;
+  const ledger = readClaimsLedger(spec);
+  return {
+    rubric: p.check.rubric,
+    inputs: {
+      persona: {
+        identity: str(p.identity),
+        stance: str(p.stance),
+        may_assert: texts(p.may_assert),
+        will_not_say: texts(p.will_not_say),
+      },
+      claims: ledger.path ? ledger.lines.filter((l) => !l.problem).map((l) => l.text) : null,
+      draft: draft.text,
+    },
+    verdict_schema: {
+      type: "object",
+      required: ["breaks"],
+      properties: {
+        breaks: {
+          type: "array",
+          description: "every place the persona breaks; empty when it holds",
+          items: {
+            type: "object",
+            required: ["evidence", "kind", "why"],
+            properties: {
+              evidence: { type: "string", description: "the passage, copied verbatim from the draft, at least three words" },
+              kind: { enum: ledger.path ? [...PERSONA_KINDS] : PERSONA_KINDS.filter((k) => k !== "unsourced_fact") },
+              why: { type: "string" },
+            },
+          },
+        },
+      },
+    },
+    key: null,
+  };
+}
+
+// Every problem with the verdict, as findings; every evidence span must be in the draft.
+export function validate(verdict, pkt, t) {
+  if (!isObject(verdict)) return [t.shape("the verdict is not a JSON object", "Write one object: { breaks }.")];
+  if (!Array.isArray(verdict.breaks)) return [t.shape("breaks is missing or not a list", "Give breaks: one { evidence, kind, why } per break, or [] when the persona holds.")];
+  const out = [];
+  verdict.breaks.forEach((b, i) => {
+    const at = `breaks[${i}]`;
+    if (!isObject(b)) { out.push(t.shape(`${at} is not an object`, "Write each break as { evidence, kind, why }.")); return; }
+    if (!PERSONA_KINDS.includes(b.kind)) {
+      const shown = typeof b.kind === "string" ? `"${b.kind}"` : b.kind === undefined ? "(missing)" : JSON.stringify(b.kind);
+      out.push(t.finding("judge-persona-kind-unknown", `${at}.kind ${shown} is not one of ${PERSONA_KINDS.join(", ")}`, `Set kind to one of ${PERSONA_KINDS.join(", ")}.`));
+    } else if (b.kind === "unsourced_fact" && pkt.inputs.claims === null) {
+      out.push(t.finding("judge-persona-no-ledger", `${at}.kind is unsourced_fact, but the spec declares no claims ledger, so no fact can be checked against sources`, "Drop this break, or report it as another kind if the voice breaks there too."));
+    }
+    if (!nonEmpty(b.why)) out.push(t.shape(`${at}.why is missing or empty`, "Say why, in a sentence."));
+    out.push(...t.evidence(b.evidence, `${at}.evidence`));
+  });
+  return out;
+}
+
+// Passes when there is no break; each break is a failure at its passage's line.
+export function derive(verdict, pkt, t) {
+  const stance = pkt.inputs.persona.stance;
+  const said = {
+    stance: [`the persona leaves its stance (${stance})`, `Revise the passage so it speaks as a ${stance} throughout.`],
+    assertion: ["the persona asserts what it may not", "Cut the assertion, or revise it into something persona.may_assert allows."],
+    will_not_say: ["the persona says what it will not say", "Cut what persona.will_not_say rules out."],
+    unsourced_fact: ["the persona states a fact the claims ledger does not hold", "Source the fact and add it to the claims ledger, or cut it."],
+  };
+  const findings = verdict.breaks.map((b) => {
+    const [message, fix] = said[b.kind];
+    return t.finding("judge-persona-break", `${message}: ${b.why.trim()}`, fix, t.lineOf(b.evidence));
+  });
+  return { status: findings.length ? "fail" : "pass", findings };
+}

package/src/judges/reader.mjs

@@ -0,0 +1,111 @@
+// The reader: a judge reads the draft as the person the audience block describes, knowing only
+// what they know, and reports every place it got lost, where (if anywhere) it stopped reading, and
+// what it would do next. hyperspec writes the packet, checks every quoted span against the draft
+// (src/judge.mjs's evidence rule) and derives the status: pass when the reader read to the end and
+// would take the next step now. A place the reader got lost is a warning, not a failure: it is where
+// to look first, and a reader who got lost and kept going still arrived.
+
+import { str } from "../placeholder.mjs";
+
+export const name = "reader";
+
+export const READER_INSTRUCTIONS = [
+  "Read inputs.draft as the reader inputs.audience describes: where and how they read it, knowing only what they know and believing what they believe now.",
+  "For every place you got lost (a term you do not know, a step that does not follow, a sentence you had to read twice), add an entry to lost_at: the passage as evidence, copied verbatim from inputs.draft, at least three whole words, and why.",
+  "If you would stop reading before the end, set stopped_at to the passage where you stopped, quoted the same way, and why; if you would read to the end, set stopped_at to null.",
+  "Then say in next_step what you would do next, in your own words, and whether you would do it now (would_take_next_step).",
+  "Answer only in the verdict shape given in verdict_schema.",
+].join(" ");
+
+const isObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const texts = (v) => (Array.isArray(v) ? v.map(str).filter(Boolean) : []);
+const nonEmpty = (v) => typeof v === "string" && v.trim().length > 0;
+
+// null when the reader applies: it needs a written audience block whose check names a rubric.
+export function skipReason(spec) {
+  const audience = spec.data?.writing?.audience;
+  if (!isObject(audience)) return "writing.audience is not written (deferred)";
+  if (!str(audience.check?.rubric)) return "writing.audience.check has no rubric";
+  return null;
+}
+
+const passageSchema = (what) => ({
+  type: "object",
+  required: ["evidence", "why"],
+  properties: {
+    evidence: { type: "string", description: `the passage ${what}, copied verbatim from the draft, at least three words` },
+    why: { type: "string" },
+  },
+});
+
+// The packet's rubric (audience.check.rubric, verbatim), inputs (the audience block's reader fields
+// and the draft) and verdict schema. No answer key.
+export function packet(spec, draft) {
+  const a = spec.data.writing.audience;
+  return {
+    rubric: a.check.rubric,
+    inputs: {
+      audience: {
+        who: str(a.who),
+        funnel_now: str(a.funnel_now),
+        knows: texts(a.knows),
+        terms: texts(a.terms),
+        believes_now: str(a.believes_now),
+        wants: str(a.wants),
+        reads_on: str(a.reads_on),
+        reader: str(a.reader),
+      },
+      draft: draft.text,
+    },
+    verdict_schema: {
+      type: "object",
+      required: ["lost_at", "stopped_at", "would_take_next_step", "next_step"],
+      properties: {
+        lost_at: { type: "array", description: "every place the reader got lost; empty when nowhere", items: passageSchema("where the reader got lost") },
+        stopped_at: { anyOf: [{ type: "null" }, passageSchema("where the reader stopped reading")], description: "null when the reader read to the end" },
+        would_take_next_step: { type: "boolean", description: "whether the reader would take next_step now" },
+        next_step: { type: "string", description: "what the reader would do next, in their own words" },
+      },
+    },
+    key: null,
+  };
+}
+
+// The problems with one quoted passage ({ evidence, why }) at `at`.
+function passageProblems(p, at, t) {
+  if (!isObject(p)) return [t.shape(`${at} is not an object`, "Write it as { evidence, why }.")];
+  const out = [];
+  if (!nonEmpty(p.why)) out.push(t.shape(`${at}.why is missing or empty`, "Say why, in a sentence."));
+  out.push(...t.evidence(p.evidence, `${at}.evidence`));
+  return out;
+}
+
+// Every problem with the verdict, as findings; every evidence span must be in the draft.
+export function validate(verdict, pkt, t) {
+  if (!isObject(verdict)) return [t.shape("the verdict is not a JSON object", "Write one object: { lost_at, stopped_at, would_take_next_step, next_step }.")];
+  const out = [];
+  if (!Array.isArray(verdict.lost_at)) out.push(t.shape("lost_at is missing or not a list", "Give lost_at: one { evidence, why } per place the reader got lost, or [] when there is none."));
+  else verdict.lost_at.forEach((p, i) => out.push(...passageProblems(p, `lost_at[${i}]`, t)));
+  if (!Object.hasOwn(verdict, "stopped_at")) out.push(t.shape("stopped_at is missing", "Set stopped_at to { evidence, why } where the reader stopped, or to null when they read to the end."));
+  else if (verdict.stopped_at !== null) out.push(...passageProblems(verdict.stopped_at, "stopped_at", t));
+  if (typeof verdict.would_take_next_step !== "boolean") out.push(t.shape("would_take_next_step is missing or not true or false", "Set would_take_next_step to the JSON boolean true or false."));
+  if (!nonEmpty(verdict.next_step)) out.push(t.shape("next_step is missing or empty", "Say what the reader would do next, in their words."));
+  return out;
+}
+
+// Passes when the reader read to the end and would take the next step now; every place it got lost
+// is a warning at the passage's line.
+export function derive(verdict, pkt, t) {
+  const findings = verdict.lost_at.map((p) => ({
+    ...t.finding("judge-reader-lost", `the reader got lost here: ${p.why.trim()}`, "Define, cut or reorder what lost this reader, for what they know now.", t.lineOf(p.evidence)),
+    severity: "warn",
+  }));
+  if (verdict.stopped_at) {
+    findings.push(t.finding("judge-reader-stopped", `the reader stopped reading here: ${verdict.stopped_at.why.trim()}`, "Revise the passage the reader stopped at so this reader keeps going, then prepare and judge again.", t.lineOf(verdict.stopped_at.evidence)));
+  }
+  if (!verdict.would_take_next_step) {
+    findings.push(t.finding("judge-reader-next-step", `the reader would not take the next step now (their next step: ${verdict.next_step.trim()})`, "Revise the draft so this reader wants to act on it now, then prepare and judge again."));
+  }
+  const status = verdict.stopped_at || !verdict.would_take_next_step ? "fail" : "pass";
+  return { status, findings };
+}