@supersuit/hyperspec 0.8.0 → 0.9.1

package/src/judges/index.mjs

@@ -9,7 +9,11 @@
 // packet whose inputs went out of date stale rather than edited; such a station also carries
 // sourceSkip(spec, draft), the skip reason when it skips because of those files (else null), so a
 // packet whose station stopped applying for that reason is stale too, and any other skip is not. The packet and key a station receives are
-// always the ones record rebuilt from the spec and draft on disk, never read from a file; see
+// always the ones record rebuilt from the spec and draft on disk, never read from a file. A
+// station that writes one packet per variant (the panel: one per reader) also carries variants(spec),
+// the list of { id, ... } it writes packets for, and variantOf(packet), the id a packet names;
+// packet() then receives the variant as a third argument, the file is <station>-<id>.packet.json,
+// and derive may return triage, the findings `hyperspec triage` answers. See
 // src/judge.mjs for the framework that calls them. Adding a judge is one file plus one line here.
 
 import * as doctor from "./doctor.mjs";
@@ -18,6 +22,7 @@ import * as reader from "./reader.mjs";
 import * as persona from "./persona.mjs";
 import * as attribution from "./attribution.mjs";
 import * as knowledge from "./knowledge.mjs";
+import * as panel from "./panel.mjs";
 
 export const JUDGES = Object.freeze([
   { name: doctor.name, instructions: doctor.DOCTOR_INSTRUCTIONS, skipReason: doctor.skipReason, packet: doctor.packet, validate: doctor.validate, derive: doctor.derive },
@@ -26,6 +31,7 @@ export const JUDGES = Object.freeze([
   { name: persona.name, instructions: persona.PERSONA_INSTRUCTIONS, skipReason: persona.skipReason, packet: persona.packet, validate: persona.validate, derive: persona.derive, inputSources: persona.inputSources, sourceSkip: persona.sourceSkip },
   { name: attribution.name, instructions: attribution.ATTRIBUTION_INSTRUCTIONS, skipReason: attribution.skipReason, packet: attribution.packet, validate: attribution.validate, derive: attribution.derive },
   { name: knowledge.name, instructions: knowledge.KNOWLEDGE_INSTRUCTIONS, skipReason: knowledge.skipReason, packet: knowledge.packet, validate: knowledge.validate, derive: knowledge.derive },
+  { name: panel.name, instructions: panel.PANEL_INSTRUCTIONS, skipReason: panel.skipReason, packet: panel.packet, validate: panel.validate, derive: panel.derive, variants: panel.variants, variantOf: panel.variantOf },
 ]);
 
 export const JUDGE_NAMES = Object.freeze(JUDGES.map((j) => j.name));

package/src/judges/panel.mjs

@@ -0,0 +1,135 @@
+// The panel (hyperspec 0.9): the draft read by several readers at once, each through their own
+// lens, the way a draft is pressure-tested by hand before it ships. Every other judgment station
+// asks one question with a right answer; the panel asks each reader what works, what to improve,
+// what is missing and what to remove, and every answer is a finding somebody has to answer.
+//
+// One packet per reader (panel-<id>.packet.json): the readers writing.panel declares, or with none
+// declared the default three (a skeptic, a newcomer and an expert), and always the spec's own
+// audience reader, added last as "buyer", because a panel that never includes the person the piece
+// is for tests everything except whether it works. Every item a reader lists carries evidence
+// copied from the draft (src/evidence.mjs's rule; a missing item anchors to the passage nearest
+// where it belongs), so a review can never be of a stale or truncated copy.
+//
+// The panel never fails a draft: its findings are warnings, and each improve, missing and remove
+// item goes to the triage file (src/triage.mjs), where the operator answers it and `check` holds
+// every answer to the draft. What works is counted, never triaged: there is nothing to answer.
+
+import { str } from "../placeholder.mjs";
+
+export const name = "panel";
+
+export const PANEL_INSTRUCTIONS = [
+  "Read inputs.draft as inputs.reader: the person inputs.reader.who describes, knowing only what inputs.reader.knows lists and what anyone would, reading for inputs.reader.lens.",
+  "List what works for this reader under good, what should change under improve, what this reader needs that the draft does not give under missing, and what should go under remove.",
+  "Every item is { evidence, note }. evidence is a passage copied verbatim from inputs.draft, at least three whole words; for a missing item, quote the passage nearest to where the missing thing belongs. note says what and why, in a sentence, in this reader's terms.",
+  "A list may be empty. Report what this reader would say, not what another reader would.",
+  "Answer only in the verdict shape given in verdict_schema.",
+].join(" ");
+
+// The default panel, used when writing.panel is not declared. The buyer is added to it, as to any.
+export const DEFAULT_PANEL = Object.freeze([
+  Object.freeze({ id: "skeptic", who: "a skeptic who doubts the piece's central claim and wants it earned", knows: Object.freeze([]), lens: "what is asserted without support, overstated, or does not follow" }),
+  Object.freeze({ id: "novice", who: "a newcomer to the subject, meeting its ideas for the first time", knows: Object.freeze([]), lens: "every term, step or assumption the piece does not explain" }),
+  Object.freeze({ id: "expert", who: "an expert in the piece's subject", knows: Object.freeze([]), lens: "what is wrong, out of date, oversimplified or missing for someone who knows the field" }),
+]);
+
+export const KINDS = Object.freeze(["good", "improve", "missing", "remove"]);
+
+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 panel applies: its buyer is the audience's reader, so it needs a written audience
+// block whose check names a rubric, the reader station's own condition.
+export function skipReason(spec) {
+  const audience = spec.data?.writing?.audience;
+  if (!isObject(audience)) return "writing.audience is not written (deferred); the panel's buyer is the audience's reader";
+  if (!str(audience.check?.rubric)) return "writing.audience.check has no rubric";
+  return null;
+}
+
+// Every reader on this spec's panel, in order: the declared readers (or the default three), then
+// the buyer. Each is { id, who, knows, lens }.
+export function variants(spec) {
+  const declared = spec.data?.writing?.panel;
+  const readers = Array.isArray(declared) && declared.length
+    ? declared.filter(isObject).map((r) => ({ id: str(r.id), who: str(r.who), knows: texts(r.knows), lens: str(r.lens) })).filter((r) => r.id && r.id !== "buyer")
+    : DEFAULT_PANEL.map((r) => ({ id: r.id, who: r.who, knows: [...r.knows], lens: r.lens }));
+  const a = spec.data.writing.audience;
+  const buyer = { id: "buyer", who: str(a.who), knows: texts(a.knows), lens: `what they want from this piece: ${str(a.wants)}` };
+  return [...readers, buyer];
+}
+
+// Which reader a packet is for, as it says; record rebuilds the packet for that reader and
+// compares every byte, so a changed name is caught with the rest.
+export const variantOf = (packet) => packet?.inputs?.reader?.id;
+
+const itemSchema = {
+  type: "object",
+  required: ["evidence", "note"],
+  properties: {
+    evidence: { type: "string", description: "a passage copied verbatim from the draft, at least three words; for a missing item, the passage nearest where it belongs" },
+    note: { type: "string", description: "what and why, in a sentence" },
+  },
+};
+
+// The packet's rubric (audience.check.rubric, verbatim: the buyer's test is the piece's), inputs
+// (the reader and the draft) and verdict schema. No answer key.
+export function packet(spec, draft, reader) {
+  return {
+    rubric: spec.data.writing.audience.check.rubric,
+    inputs: {
+      reader: { id: reader.id, who: reader.who, knows: reader.knows, lens: reader.lens },
+      draft: draft.text,
+    },
+    verdict_schema: {
+      type: "object",
+      required: [...KINDS],
+      properties: {
+        good: { type: "array", description: "what works for this reader; empty when nothing does", items: itemSchema },
+        improve: { type: "array", description: "what should change", items: itemSchema },
+        missing: { type: "array", description: "what this reader needs that the draft does not give", items: itemSchema },
+        remove: { type: "array", description: "what should go", items: itemSchema },
+      },
+    },
+    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: { good, improve, missing, remove }.")];
+  const out = [];
+  for (const kind of KINDS) {
+    if (!Array.isArray(verdict[kind])) { out.push(t.shape(`${kind} is missing or not a list`, `Give ${kind}: one { evidence, note } per item, or [] when there is none.`)); continue; }
+    verdict[kind].forEach((item, i) => {
+      const at = `${kind}[${i}]`;
+      if (!isObject(item)) { out.push(t.shape(`${at} is not an object`, "Write it as { evidence, note }.")); return; }
+      if (!nonEmpty(item.note)) out.push(t.shape(`${at}.note is missing or empty`, "Say what and why, in a sentence."));
+      out.push(...t.evidence(item.evidence, `${at}.evidence`));
+    });
+  }
+  return out;
+}
+
+const WORD = { improve: "would improve", missing: "misses", remove: "would remove" };
+
+// Always passes: every improve, missing and remove item is a warning at its evidence's line, and a
+// finding for the triage file. The summary counts all four lists.
+export function derive(verdict, pkt, t) {
+  const reader = pkt.inputs.reader.id;
+  const findings = [];
+  const triage = [];
+  for (const kind of ["improve", "missing", "remove"]) {
+    for (const item of verdict[kind]) {
+      const note = item.note.trim();
+      if (kind === "improve") findings.push({ ...t.finding("judge-panel-improve", `${reader} ${WORD[kind]} this: ${note}`, "Answer it in the triage file: take it, keep the passage with a reason, show it is already true, or leave it open for a decision.", t.lineOf(item.evidence)), severity: "warn" });
+      if (kind === "missing") findings.push({ ...t.finding("judge-panel-missing", `${reader} ${WORD[kind]} something here: ${note}`, "Answer it in the triage file: take it, keep the passage with a reason, show it is already true, or leave it open for a decision.", t.lineOf(item.evidence)), severity: "warn" });
+      if (kind === "remove") findings.push({ ...t.finding("judge-panel-remove", `${reader} ${WORD[kind]} this: ${note}`, "Answer it in the triage file: take it, keep the passage with a reason, show it is already true, or leave it open for a decision.", t.lineOf(item.evidence)), severity: "warn" });
+      triage.push({ kind, text: note, evidence: item.evidence });
+    }
+  }
+  const n = (k) => verdict[k].length;
+  const summary = `${reader}: ${n("good")} good, ${n("improve")} to improve, ${n("missing")} missing, ${n("remove")} to remove`;
+  return { status: "pass", findings, summary, triage };
+}

package/src/segments.mjs

@@ -182,6 +182,50 @@ export function splitSegments(text, { by = "paragraph" } = {}) {
   return spans.map((s, i) => ({ id: `s${i + 1}`, start: s.start, end: s.end, label: "unlabeled", text: text.slice(s.start, s.end) }));
 }
 
+// -------------------------------------------------------------------------------------------
+// carrySegments: re-marking an edited material without relabeling what did not change (0.9.1).
+// A label is a fact about a stretch of text, so while the same text (compared trimmed) is still in
+// the material, its label is still true. `fresh` is what splitSegments returned for the material as
+// it reads now; `old` is the segment objects of the file it was marked in before. Each fresh
+// segment whose trimmed text an old segment has takes that old segment's id, label and every other
+// key it carries (own, source, teller, speaker, anything a person added), with start, end and text
+// from the new split. The id is carried too, because the spine cites segments by id: "m1#s3" keeps
+// pointing at the words it pointed at. Old segments with the same text are used in document order,
+// each once. A fresh segment no old one matches stays "unlabeled" and gets the next id no old
+// segment used, "s<n>" counting up past the highest. Returns { segments, carried, unlabeled }:
+// carried counts the segments that took a label other than "unlabeled"; unlabeled lists every
+// segment still to label, in document order.
+export function carrySegments(fresh, old) {
+  const byText = new Map();
+  for (const o of old) {
+    if (!o || typeof o !== "object" || typeof o.text !== "string") continue;
+    const k = o.text.trim();
+    if (!byText.has(k)) byText.set(k, []);
+    byText.get(k).push(o);
+  }
+  const taken = new Set(old.map((o) => str(o?.id)).filter(Boolean));
+  let n = Math.max(0, ...[...taken].map((id) => Number(/^s(\d+)$/.exec(id)?.[1] ?? 0)));
+  const nextId = () => {
+    do n += 1; while (taken.has(`s${n}`));
+    taken.add(`s${n}`);
+    return `s${n}`;
+  };
+  const segments = [];
+  let carried = 0;
+  for (const seg of fresh) {
+    const match = byText.get(seg.text.trim())?.shift();
+    if (!match) {
+      segments.push({ id: nextId(), start: seg.start, end: seg.end, label: "unlabeled", text: seg.text });
+      continue;
+    }
+    const { id, start, end, label, text, ...extra } = match;
+    const kept = { id: str(id) || nextId(), start: seg.start, end: seg.end, label: typeof label === "string" && label ? label : "unlabeled", ...extra, text: seg.text };
+    if (kept.label !== "unlabeled") carried += 1;
+    segments.push(kept);
+  }
+  return { segments, carried, unlabeled: segments.filter((s) => s.label === "unlabeled") };
+}
+
 // -------------------------------------------------------------------------------------------
 // readSegments: parse + validate a marked-up segments file. Never throws on a bad or missing
 // file; every failure mode becomes a finding in the lint shape (test, id, severity, message, fix),

package/src/stations/index.mjs

@@ -3,7 +3,7 @@
 // src/check.mjs calls; adding a station is adding one file plus one line here, which is the whole
 // point of the registry existing rather than check.mjs importing each station by name itself.
 //
-// The order: form, terms, claims, quotes, private, dna, links, sequence. quotes and private share ctx (util.mjs's
+// The order: form, terms, claims, quotes, private, dna, links, sequence, triage. quotes and private share ctx (util.mjs's
 // markedSegments caches the spec's marked materials there), so a check run reads them once.
 
 import * as form from "./form.mjs";
@@ -14,6 +14,7 @@ import * as privateStation from "./private.mjs";
 import * as dna from "./dna.mjs";
 import * as links from "./links.mjs";
 import * as sequence from "./sequence.mjs";
+import * as triage from "./triage.mjs";
 
 export const STATIONS = Object.freeze([
   { name: form.name, run: form.run },
@@ -24,6 +25,7 @@ export const STATIONS = Object.freeze([
   { name: dna.name, run: dna.run },
   { name: links.name, run: links.run },
   { name: sequence.name, run: sequence.run },
+  { name: triage.name, run: triage.run },
 ]);
 
 export const STATION_NAMES = Object.freeze(STATIONS.map((s) => s.name));

package/src/stations/quotes.mjs

@@ -33,6 +33,14 @@
 // story segment is enough. Sentences come from splitSegments(text, { by: "sentence" }), and every
 // sentence the span overlaps is read, so a curly quote the splitter cuts in two still keeps its
 // attribution.
+//
+// Example phrasings (hyperspec 0.9). A primer shows the reader what to type or say: "write the
+// update for Dana" is an example, not a quotation, and no material holds it. writing.quotes.examples
+// says which quoted spans are examples. `true` makes every span whose sentence names no known
+// speaker an example: it passes unmatched, and a quotation that names its speaker is still held to
+// the materials. A list names the example phrasings themselves, compared the way a span is matched,
+// so every other span is still checked. The list is the stricter choice: under `true`, an invented
+// quotation that names no one passes too.
 
 import { splitSegments } from "../segments.mjs";
 import { STOPWORDS, wordsOf } from "../dna.mjs";
@@ -75,6 +83,18 @@ export function quotedSpans(text) {
   return spans;
 }
 
+// The spec's example setting: { all: true } for `examples: true`, { phrases } (a Set of match keys)
+// for a list, or null when the spec declares none, or `false`.
+export function examplesOf(spec) {
+  const raw = spec?.data?.writing?.quotes?.examples;
+  if (str(raw) === "true") return { all: true };
+  if (Array.isArray(raw)) {
+    const phrases = new Set(raw.map(str).filter(Boolean).map(matchKey).filter(Boolean));
+    return phrases.size ? { phrases } : null;
+  }
+  return null;
+}
+
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 const STOPWORD_SET = new Set(STOPWORDS);
@@ -133,13 +153,19 @@ export function run(spec, draft, ctx) {
     .filter((sp) => sp.re);
 
   const sentences = splitSegments(text, { by: "sentence" });
+  const examples = examplesOf(spec);
   const findings = [];
   for (const span of spans) {
     const key = matchKey(span.inner);
     if (!key) continue;
+    if (examples?.phrases?.has(key)) continue;
     const shown = truncate(span.inner.replace(/\s+/g, " "), 80);
     const line = lineAt(draft.text, span.start);
     const hits = sources.filter((s) => s.norm.includes(key));
+    const around = attributionContext(text, sentences, span);
+    const named = speakers.filter((sp) => sp.re.test(around)).map((sp) => sp.key);
+    // examples: true reads a span that names no known speaker as an example phrasing.
+    if (examples?.all && !named.length) continue;
     if (!hits.length) {
       findings.push({
         station: name,
@@ -151,8 +177,6 @@ export function run(spec, draft, ctx) {
       });
       continue;
     }
-    const around = attributionContext(text, sentences, span);
-    const named = speakers.filter((sp) => sp.re.test(around)).map((sp) => sp.key);
     if (named.length && !hits.some((h) => h.label === "quote" && named.includes(h.speaker))) {
       const who = named.map((k) => shownSpeaker.get(k) ?? k).join(", ");
       findings.push({

package/src/stations/sequence.mjs

@@ -20,9 +20,18 @@
 //   numbering  unit numbers increase through the work
 //   pointers   (warning) a "<unit> N" pointer to a later unit is reported, so it stays a pointer
 //              and never becomes a dependency
+//   quiz       (hyperspec 0.9, only when sequence.quiz names the quiz heading) every defined term is
+//              tested by some question, a simple plural counting; no question uses a term defined
+//              after the unit it is tagged with; every question is tagged; every answer names one
+//              of its question's options. Promoted from the checker the first book written this
+//              way used, so the rules and the question shape are that checker's.
 //
 // A use is a whole-word, case-insensitive match, where a hyphen is part of a word: "context-aware"
-// does not use "context", and "skills" does not use "skill". The station reads the outline from
+// does not use "context", and "skills" does not use "skill". A word inside a longer defined term is
+// not a use of the shorter one (hyperspec 0.9.1): with "level" and "thinking level" both defined,
+// "thinking level" and "thinking levels" use only "thinking level", and "level" on its own still
+// uses "level". Every guard that looks for a use (order, quiz order, quiz coverage) masks the
+// longer terms first. The station reads the outline from
 // disk, resolved against the spec's folder, the way claims reads its ledger. It never reads a
 // part's text for meaning: a term used in a sense other than its definition still counts as a use.
 
@@ -60,6 +69,7 @@ export function sequenceOf(spec) {
     termsSection: str(raw.terms_section) || DEFAULTS.terms_section,
     teaser: str(raw.teaser) || DEFAULTS.teaser,
     outline: str(raw.outline) || null,
+    quiz: str(raw.quiz) || null,
     knows: new Set(knows),
   };
 }
@@ -193,6 +203,99 @@ function firstUse(unit, prose, term) {
   return i < 0 ? 0 : unit.startLine + i;
 }
 
+// Whether `text` (code already masked) uses `term`, by the same whole-word rule as firstUse.
+const usesTerm = (text, term) => new RegExp(`(^|[^a-z0-9-])${escapeRe(term)}([^a-z0-9-]|$)`, "i").test(text);
+
+// For each defined term, the other defined terms that contain it as a whole-word phrase, longest
+// first: { level: ["thinking level"] }. A term no other term contains maps to [].
+export function longerTerms(terms) {
+  const all = [...terms];
+  return new Map(all.map((t) => [t, all.filter((u) => u !== t && usesTerm(u, t)).sort((a, b) => b.length - a.length)]));
+}
+
+// `text` with every whole-word occurrence of each `longer` term, a trailing plural "s" included,
+// blanked to spaces. Line breaks survive, so a line number still maps to the same line, and a term
+// broken across two lines is blanked on both.
+export function maskLonger(text, longer) {
+  let out = text;
+  for (const t of longer) {
+    const re = new RegExp(`(?<![a-z0-9-])${escapeRe(t).replace(/ /g, "\\s+")}s?(?![a-z0-9-])`, "gi");
+    out = out.replace(re, (m) => m.replace(/[^\n]/g, " "));
+  }
+  return out;
+}
+
+// Every quiz in the draft, read the way the first book written to this shape wrote it:
+//
+//   ## Check yourself: Part 1
+//
+//   1. *(Lesson 1)* You type "draft an email" into a chat app. What did you just send?
+//      - a) A file on your computer
+//      - b) A prompt, sent to a chat app
+//   ...
+//   **Answers:** 1 b · 2 c
+//
+// A quiz starts at an ATX heading whose text starts with `quiz` (any case) and runs to the next
+// heading of its own level or above, or the end of its file. A question is a numbered line tagged
+// "*(<unit> N)*"; it runs to the next numbered line, the answers line or the quiz's end, and its
+// options are the indented "- a) " lines inside it. The answers line is "**Answers:**" followed by
+// "<number> <letter>" pairs, in any separator. Returns { quizzes, questions, untagged }: quizzes
+// counts the quiz headings; each question is { n, unit, line, text, options, answer }, text with
+// code masked (code is not prose), line 1-based in the draft; untagged lists { n, line } for a
+// numbered line in a quiz that carries no tag.
+export function parseQuizzes(draft, { unit, quiz }) {
+  const lines = maskCode(draft.text).split("\n").map((l) => l.replace(/\r$/, ""));
+  const quizRe = new RegExp(`^${escapeRe(quiz)}`, "i");
+  const fileEnds = new Set(list(draft.sources).map((s) => s.startLine + s.lineCount - 1));
+  const numbered = /^[ \t]{0,3}(\d+)\.[ \t]/;
+  const tagged = new RegExp(`^[ \\t]{0,3}(\\d+)\\.[ \\t]+\\*\\([ \\t]*${escapeRe(unit)}[ \\t]+(\\d+)[ \\t]*\\)\\*`, "i");
+  const answersRe = /^[ \t]*\*\*Answers:?\*\*:?(.*)$/i;
+  const optionRe = /^[ \t]+[-*+][ \t]+([a-z])\)[ \t]/i;
+  const out = { quizzes: 0, questions: [], untagged: [] };
+  for (let i = 0; i < lines.length; i++) {
+    const h = ATX.exec(lines[i]);
+    if (!h || !quizRe.test((h[2] ?? "").replace(/(^|[ \t]+)#+[ \t]*$/, "").trim())) continue;
+    out.quizzes += 1;
+    const level = h[1].length;
+    // [i + 1, end): stops before a heading of its level or above, or after its file's last line
+    // (fileEnds holds 1-based line numbers, so fileEnds.has(end) says line index end - 1 was one).
+    let end = i + 1;
+    while (end < lines.length && !fileEnds.has(end)) {
+      const next = ATX.exec(lines[end]);
+      if (next && next[1].length <= level) break;
+      end++;
+    }
+    const answers = new Map();
+    let cur = null;
+    const qs = [];
+    const flush = () => { if (cur) qs.push(cur); cur = null; };
+    for (let j = i + 1; j < end; j++) {
+      const a = answersRe.exec(lines[j]);
+      if (a) {
+        flush();
+        for (const m of a[1].matchAll(/(\d+)[ \t]+([a-z])(?![a-z])/gi)) answers.set(Number(m[1]), m[2].toLowerCase());
+        continue;
+      }
+      const t = tagged.exec(lines[j]);
+      if (t) {
+        flush();
+        cur = { n: Number(t[1]), unit: Number(t[2]), line: j + 1, text: lines[j], options: [] };
+        continue;
+      }
+      const u = numbered.exec(lines[j]);
+      if (u) { flush(); out.untagged.push({ n: Number(u[1]), line: j + 1 }); continue; }
+      if (!cur) continue;
+      cur.text += `\n${lines[j]}`;
+      const o = optionRe.exec(lines[j]);
+      if (o) cur.options.push(o[1].toLowerCase());
+    }
+    flush();
+    for (const q of qs) out.questions.push({ ...q, answer: answers.get(q.n) ?? null });
+    i = end - 1;
+  }
+  return out;
+}
+
 // One finding, in the shape every station returns; line only when there is one to point at.
 const finding = ({ id, severity, message, fix, line }) => ({ station: name, id, severity, ...(line ? { line } : {}), message, fix });
 
@@ -228,12 +331,17 @@ export function run(spec, draft) {
   }
 
   // order: no unit before the defining one uses the term.
+  // A longer defined term that contains the term is masked first: "thinking level" is not a use of
+  // "level".
   const prose = new Map(units.map((u) => [u, proseOf(u, seq, { withTerms: false })]));
+  const longer = longerTerms(definedAt.keys());
   for (const [t, at] of definedAt) {
     if (seq.knows.has(t)) continue;
+    const sups = longer.get(t);
     for (const u of units) {
       if (u === at) break;
-      const line = firstUse(u, prose.get(u), t);
+      const lines = sups.length ? maskLonger(prose.get(u).join("\n"), sups).split("\n") : prose.get(u);
+      const line = firstUse(u, lines, t);
       if (line) findings.push(finding({ id: "station-sequence-used-before-defined", severity: "fail", message: `${U} ${u.n} uses "${t}" before ${U} ${at.n} defines it`, fix: `Rewrite ${U} ${u.n} without "${t}", define it earlier, or add it to writing.form.sequence.knows if the reader already has the word.`, line: line }));
     }
   }
@@ -270,6 +378,45 @@ export function run(spec, draft) {
     });
   }
 
+  // quiz: only when the spec names the quiz heading.
+  if (seq.quiz) findings.push(...quizFindings(draft, seq, definedAt));
+
   const status = findings.some((f) => f.severity === "fail") ? "fail" : "pass";
   return { station: name, status, findings };
 }
+
+// The quiz guards, against the terms the units define (term -> defining unit).
+function quizFindings(draft, seq, definedAt) {
+  const U = seq.unit;
+  const out = [];
+  const { quizzes, questions, untagged } = parseQuizzes(draft, seq);
+  // Every question's text with each term's longer defined terms masked, as the order guard reads
+  // prose: "thinking level" in a question neither uses nor tests "level".
+  const longer = longerTerms(definedAt.keys());
+  const masked = (q, t) => (longer.get(t).length ? maskLonger(q.text, longer.get(t)) : q.text);
+  const uses = (q, t) => usesTerm(masked(q, t), t);
+  const tests = (q, t) => { const text = masked(q, t); return usesTerm(text, t) || usesTerm(text, `${t}s`); };
+  if (!quizzes) {
+    return [finding({ id: "station-sequence-quiz-missing", severity: "fail", message: `no "${seq.quiz}" heading in the draft, and writing.form.sequence.quiz names one`, fix: `Add a "## ${seq.quiz}" section of questions, or delete quiz: from the spec.` })];
+  }
+  for (const q of untagged) {
+    out.push(finding({ id: "station-sequence-quiz-untagged", severity: "fail", message: `question ${q.n} names no ${U.toLowerCase()} it tests`, fix: `Start the question "${q.n}. *(${U} N)* ...", naming the ${U.toLowerCase()} it tests.`, line: q.line }));
+  }
+  for (const q of questions) {
+    if (!q.answer || !q.options.includes(q.answer)) {
+      const has = q.options.length ? q.options.join(", ") : "none";
+      out.push(finding({ id: "station-sequence-quiz-answer", severity: "fail", message: q.answer ? `question ${q.n}'s answer is ${q.answer}, which is not one of its options (${has})` : `question ${q.n} has no answer on the quiz's "**Answers:**" line`, fix: `Give question ${q.n} one answer, "${q.n} <letter>", naming one of its options.`, line: q.line }));
+    }
+    for (const [t, at] of definedAt) {
+      if (seq.knows.has(t) || at.n <= q.unit) continue;
+      if (uses(q, t)) out.push(finding({ id: "station-sequence-quiz-used-before-defined", severity: "fail", message: `question ${q.n}, tagged ${U} ${q.unit}, uses "${t}", which ${U} ${at.n} defines later`, fix: `Rewrite the question without "${t}", or tag it with ${U} ${at.n} or later.`, line: q.line }));
+    }
+  }
+  // coverage: a simple plural counts, so "skills" tests "skill".
+  for (const [t, at] of definedAt) {
+    if (!questions.some((q) => tests(q, t))) {
+      out.push(finding({ id: "station-sequence-quiz-untested", severity: "fail", message: `no quiz question tests "${t}", which ${U} ${at.n} defines`, fix: `Add a question that uses "${t}", tagged ${U} ${at.n} or later.`, line: at.line }));
+    }
+  }
+  return out;
+}

package/src/stations/triage.mjs

@@ -0,0 +1,20 @@
+// Station "triage" (hyperspec 0.9). Every finding a panel reader or an outside review raised about
+// the draft, held to its answer: a finding nobody answered fails, an answer that says the draft now
+// does it (taken) or already did (already-true) fails unless the passage it quotes is in the draft
+// as it is now, and a kept answer fails without its reason. An open finding is a warning: it is a
+// decision for the operator, and the draft can ship while it waits. So is an answer that kept a
+// passage, or left it open, when that passage is no longer in the draft.
+//
+// The rules and the file live in src/triage.mjs, which `hyperspec triage status` reads too, so the
+// station and the command can never disagree. With no triage file yet the station skips.
+
+import { triageState } from "../triage.mjs";
+
+export const name = "triage";
+
+export function run(spec, draft) {
+  const state = triageState(spec, draft);
+  if (state.skip) return { station: name, status: "skip", findings: [], reason: state.skip };
+  const status = state.findings.some((f) => f.severity === "fail") ? "fail" : "pass";
+  return { station: name, status, findings: state.findings };
+}