@supersuit/hyperspec 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/hyperspec",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "A hyperspec is a spec written for an agent: every decision accounted for, every requirement failable and checked, every field traced. The standard and its linter.",
   "type": "module",
   "bin": {

package/src/check.mjs

@@ -21,6 +21,7 @@ import { readDraft } from "./draft.mjs";
 import { openLedger, priorLines, ledgerDraftKey, ledgerVerdict } from "./ledger.mjs";
 import { STATIONS, STATION_NAMES } from "./stations/index.mjs";
 import { str } from "./placeholder.mjs";
+import { readSequenceDraft, sequenceFilesDecl, sourceAt } from "./sequence-draft.mjs";
 
 const present = (v) => typeof v === "string" && v.trim().length > 0;
 
@@ -95,17 +96,29 @@ export function lintBlock(spec, specPathArg) {
   };
 }
 
+// A finding from a draft assembled out of a sequence's files names the file and its own line in
+// it, rather than a line of the joined text nobody can open.
+function locate(finding, draft) {
+  const src = typeof finding.line === "number" ? sourceAt(draft, finding.line) : null;
+  return src ? { ...finding, file: src.file, line: finding.line - src.startLine + 1 } : finding;
+}
+
 // runCheck(specPathArg, draftPathArg, { only }): specPathArg and draftPathArg are exactly what
 // the CLI (or a caller) was given, never resolved, so every path this returns or writes to the
 // ledger is displayed and recorded the way the operator typed it, not as an absolute path on this
 // machine. only, when given, is an array of station names to run instead of every registered one.
+//
+// With no draftPathArg, a spec that lists writing.form.sequence.files is checked against those
+// files, joined in reading order (src/sequence-draft.mjs); any other spec still needs --draft.
 export function runCheck(specPathArg, draftPathArg, { only } = {}) {
   if (!present(specPathArg)) return { usage: true, error: "check needs a spec path" };
-  if (!present(draftPathArg)) return { usage: true, error: "check needs --draft <file>" };
+  const needsDraft = { usage: true, error: "check needs --draft <file>" };
 
   const loaded = loadWritingSpec(specPathArg, "check");
+  if (!present(draftPathArg) && (loaded.usage || !sequenceFilesDecl(loaded.spec).length)) return needsDraft;
   if (loaded.usage) return loaded;
   const { spec } = loaded;
+  const fromSequence = !present(draftPathArg);
 
   // --only: every name must be one this build's registry knows; unknown names are a usage error
   // (exit 2) rather than a silent no-op, and the run order always follows the registry, never the
@@ -123,12 +136,16 @@ export function runCheck(specPathArg, draftPathArg, { only } = {}) {
   const blocked = lintBlock(spec, specPathArg);
   if (blocked) return blocked;
 
-  // BOM stripped, CRLF-clean lines, sha256 over the raw bytes: see src/draft.mjs.
-  const draft = readDraft(draftPathArg);
-  if (!draft) return { usage: true, error: `cannot read draft: ${draftPathArg}` };
+  // BOM stripped, CRLF-clean lines, sha256 over the raw bytes: see src/draft.mjs. A sequence's
+  // draft is its files joined; its ledger key is the files entry as the spec writes it, so the
+  // history of the work stays one history as parts are added.
+  const draft = fromSequence ? readSequenceDraft(spec, specPathArg) : readDraft(draftPathArg);
+  const draftLabel = fromSequence ? sequenceFilesDecl(spec).join(", ") : draftPathArg;
+  if (!draft) return { usage: true, error: fromSequence ? `writing.form.sequence.files matches no file: ${draftLabel}` : `cannot read draft: ${draftPathArg}` };
 
   const ctx = {};
-  const results = stationsToRun.map((s) => runStation(s, spec, draft, ctx));
+  const results = stationsToRun.map((s) => runStation(s, spec, draft, ctx))
+    .map((r) => (draft.sources ? { ...r, findings: r.findings.map((f) => locate(f, draft)) } : r));
   const failing = results.filter((r) => r.status === "fail").map((r) => r.station);
   const code = failing.length ? 1 : 0;
 
@@ -146,7 +163,7 @@ export function runCheck(specPathArg, draftPathArg, { only } = {}) {
   const ledger = openLedger(spec);
   if (ledger?.warning) ledgerWarning = ledger.warning;
   else if (ledger) {
-    const draftKey = ledgerDraftKey(spec.dir, draftPathArg);
+    const draftKey = fromSequence ? draftLabel : ledgerDraftKey(spec.dir, draftPathArg);
     const specSha = sha256(readFileSync(resolve(specPathArg)));
     const statusNow = Object.fromEntries(results.map((r) => [r.station, r.status]));
 
@@ -177,7 +194,8 @@ export function runCheck(specPathArg, draftPathArg, { only } = {}) {
   return {
     ok: true,
     specPath: specPathArg,
-    draftPath: draftPathArg,
+    draftPath: draftLabel,
+    ...(fromSequence ? { files: draft.sources.map((x) => x.file) } : {}),
     draftSha256: draft.sha256,
     stations: results,
     failing,

package/src/evidence.mjs

@@ -0,0 +1,74 @@
+// The evidence rule, shared by every command that holds a quoted span to a draft: `judge record`
+// (every passage a judge cites), and `triage` (every answer that says where the draft now does
+// what a finding asked, and every finding an outside review quotes). One rule, so a span that
+// counts for a judge counts for a triage answer, and the reverse.
+//
+// A span of evidence counts as quoted from the draft when, after both are normalized, the draft
+// contains it. Normalization collapses every run of whitespace (spaces, tabs, line breaks, CRLF) to
+// one space and turns curly, low and angle quotation marks and apostrophes into their straight
+// forms (primes are not quotation marks and are left alone), so a judge that reflows a quotation or
+// types typographic quotes is still quoting; changing a single word is not.
+//
+// A span must also carry at least MIN_EVIDENCE_WORDS word tokens (runs of letters and digits), and
+// match on word boundaries: a match may not start or end in the middle of a word. A one-letter or
+// one-word "quotation" is found almost anywhere and so checks nothing.
+
+import { lineAt } from "./stations/util.mjs";
+
+export const MIN_EVIDENCE_WORDS = 3;
+const WORD_CHAR = /[\p{L}\p{N}]/u;
+export const WORD_TOKENS = /[\p{L}\p{N}]+/gu;
+
+const QUOTE_CHARS = new Map([
+  ["‘", "'"], ["’", "'"], ["‚", "'"], ["‛", "'"], ["‹", "'"], ["›", "'"],
+  ["“", '"'], ["”", '"'], ["„", '"'], ["‟", '"'], ["«", '"'], ["»", '"'],
+]);
+
+// { norm, map }: the normalized text, and for each of its characters the offset in `text` it came
+// from, so a match in the normalized text can be traced back to a line of the original.
+export function normalizeForEvidence(text) {
+  let norm = "";
+  const map = [];
+  let pendingSpace = -1;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (/\s/.test(ch)) { if (norm && pendingSpace < 0) pendingSpace = i; continue; }
+    if (pendingSpace >= 0) { norm += " "; map.push(pendingSpace); pendingSpace = -1; }
+    norm += QUOTE_CHARS.get(ch) ?? ch;
+    map.push(i);
+  }
+  return { norm, map };
+}
+
+// The number of word tokens in `span`, as the rule counts them.
+export const evidenceWords = (span) => (normalizeForEvidence(String(span)).norm.match(WORD_TOKENS) ?? []).length;
+
+// A locator bound to one text: locate(span) is the first whole-word match of `span`, as
+// { line, start, end } (1-based line; start and end are offsets into the original text, end
+// exclusive), or null. Build it once per text: normalizing is the cost.
+export function evidenceLocator(text) {
+  const { norm, map } = normalizeForEvidence(text);
+  return (span) => {
+    const needle = normalizeForEvidence(String(span ?? "")).norm;
+    if (!needle) return null;
+    const startsWord = WORD_CHAR.test(needle[0]);
+    const endsWord = WORD_CHAR.test(needle[needle.length - 1]);
+    for (let at = norm.indexOf(needle); at >= 0; at = norm.indexOf(needle, at + 1)) {
+      const before = at > 0 ? norm[at - 1] : "";
+      const after = norm[at + needle.length] ?? "";
+      if (startsWord && before && WORD_CHAR.test(before)) continue;
+      if (endsWord && after && WORD_CHAR.test(after)) continue;
+      const start = map[at];
+      return { line: lineAt(text, start), start, end: map[at + needle.length - 1] + 1 };
+    }
+    return null;
+  };
+}
+
+// Why `span` is not evidence of `locate`'s text: "missing" (empty or not a string), "too-short"
+// (fewer than MIN_EVIDENCE_WORDS words) or "not-found"; null when it is evidence.
+export function evidenceProblem(locate, span) {
+  if (typeof span !== "string" || !span.trim()) return "missing";
+  if (evidenceWords(span) < MIN_EVIDENCE_WORDS) return "too-short";
+  return locate(span) ? null : "not-found";
+}

package/src/judge.mjs

@@ -16,69 +16,27 @@ import { writeFileAtomic } from "./fsutil.mjs";
 import { readDraft } from "./draft.mjs";
 import { loadWritingSpec, lintBlock, withoutAbsolutePaths } from "./check.mjs";
 import { openLedger, priorLines, ledgerDraftKey, ledgerVerdict } from "./ledger.mjs";
-import { lineAt, truncate } from "./stations/util.mjs";
+import { truncate } from "./stations/util.mjs";
 import { JUDGES, JUDGE_NAMES } from "./judges/index.mjs";
+import { MIN_EVIDENCE_WORDS, normalizeForEvidence, evidenceLocator, evidenceWords } from "./evidence.mjs";
+import { addFindings } from "./triage.mjs";
 
 export const PACKET_VERSION = "0.1";
 
 const present = (v) => typeof v === "string" && v.trim().length > 0;
 
 // ---- the evidence rule -------------------------------------------------------------------------
-// A span of evidence counts as quoted from the draft when, after both are normalized, the draft
-// contains it. Normalization collapses every run of whitespace (spaces, tabs, line breaks, CRLF) to
-// one space and turns curly, low and angle quotation marks and apostrophes into their straight
-// forms (primes are not quotation marks and are left alone), so a judge that reflows a quotation or
-// types typographic quotes is still quoting; changing a single word is not.
-//
-// A span must also carry at least MIN_EVIDENCE_WORDS word tokens (runs of letters and digits), and
-// match on word boundaries: a match may not start or end in the middle of a word. A one-letter or
-// one-word "quotation" is found almost anywhere and so checks nothing.
-
-export const MIN_EVIDENCE_WORDS = 3;
-const WORD_CHAR = /[\p{L}\p{N}]/u;
-const WORD_TOKENS = /[\p{L}\p{N}]+/gu;
-
-const QUOTE_CHARS = new Map([
-  ["\u2018", "'"], ["\u2019", "'"], ["\u201A", "'"], ["\u201B", "'"], ["\u2039", "'"], ["\u203A", "'"],
-  ["\u201C", '"'], ["\u201D", '"'], ["\u201E", '"'], ["\u201F", '"'], ["\u00AB", '"'], ["\u00BB", '"'],
-]);
-
-// { norm, map }: the normalized text, and for each of its characters the offset in `text` it came
-// from, so a match in the normalized text can be traced back to a line of the original.
-export function normalizeForEvidence(text) {
-  let norm = "";
-  const map = [];
-  let pendingSpace = -1;
-  for (let i = 0; i < text.length; i++) {
-    const ch = text[i];
-    if (/\s/.test(ch)) { if (norm && pendingSpace < 0) pendingSpace = i; continue; }
-    if (pendingSpace >= 0) { norm += " "; map.push(pendingSpace); pendingSpace = -1; }
-    norm += QUOTE_CHARS.get(ch) ?? ch;
-    map.push(i);
-  }
-  return { norm, map };
-}
+// Lives in src/evidence.mjs, shared with `triage`; re-exported here for the callers that import it
+// from this module.
+export { MIN_EVIDENCE_WORDS, normalizeForEvidence };
 
 // The helpers a station's validate() and derive() receive, bound to one packet and one draft: every
 // finding they build has the same shape as a `check` finding ({ station, id, severity, message,
 // fix, line? }).
 function toolsFor(stationName, draft) {
-  const { norm, map } = normalizeForEvidence(draft.text);
+  const locator = evidenceLocator(draft.text);
   // The 1-based line of the first whole-word match of `span`, or -1.
-  const locate = (span) => {
-    const needle = normalizeForEvidence(span).norm;
-    if (!needle) return -1;
-    const startsWord = WORD_CHAR.test(needle[0]);
-    const endsWord = WORD_CHAR.test(needle[needle.length - 1]);
-    for (let at = norm.indexOf(needle); at >= 0; at = norm.indexOf(needle, at + 1)) {
-      const before = at > 0 ? norm[at - 1] : "";
-      const after = norm[at + needle.length] ?? "";
-      if (startsWord && before && WORD_CHAR.test(before)) continue;
-      if (endsWord && after && WORD_CHAR.test(after)) continue;
-      return lineAt(draft.text, map[at]);
-    }
-    return -1;
-  };
+  const locate = (span) => locator(span)?.line ?? -1;
   const finding = (id, message, fix, line) => ({ station: stationName, id, severity: "fail", message, fix, ...(typeof line === "number" && line > 0 ? { line } : {}) });
   return {
     finding,
@@ -88,7 +46,7 @@ function toolsFor(stationName, draft) {
       if (typeof value !== "string" || !value.trim()) {
         return [finding("judge-evidence-missing", `${where} is empty or not a string`, "Quote the span of the draft this judgment rests on, verbatim.")];
       }
-      const words = (normalizeForEvidence(value).norm.match(WORD_TOKENS) ?? []).length;
+      const words = evidenceWords(value);
       if (words < MIN_EVIDENCE_WORDS) {
         return [finding("judge-evidence-too-short", `${where} has ${words} word${words === 1 ? "" : "s"}, fewer than ${MIN_EVIDENCE_WORDS}: "${truncate(value, 80)}"`, `Quote the sentence or clause the judgment rests on, at least ${MIN_EVIDENCE_WORDS} words, verbatim.`)];
       }
@@ -122,8 +80,10 @@ const packetJson = (packet) => `${JSON.stringify(packet, null, 2)}\n`;
 // key }: key is the station's hidden answer key (null for a station with none), written by prepare
 // to <station>.key.json for a person to read, and never read back as truth: record rebuilds it.
 // specPathArg and the draft's path are the strings as given, so the bytes are deterministic.
-export function buildPacket(judge, specPathArg, spec, draft, specSha) {
-  const parts = judge.packet(spec, draft);
+// variant: for a station that writes one packet per variant (the panel, one per reader), the
+// variant this packet is for; undefined for every other station.
+export function buildPacket(judge, specPathArg, spec, draft, specSha, variant) {
+  const parts = judge.packet(spec, draft, variant);
   const packet = {
     hyperspec_judge: PACKET_VERSION,
     station: judge.name,
@@ -182,14 +142,18 @@ export function prepareJudges(specPathArg, draftPathArg, outDirArg, { only, forc
   for (const judge of judges) {
     const reason = judge.skipReason(spec, draft);
     if (reason) { skipped.push({ station: judge.name, reason }); continue; }
-    let built;
-    try { built = buildPacket(judge, specPathArg, spec, draft, specSha); }
-    catch (e) {
-      crashed.push({ station: judge.name, id: `judge-${judge.name}-crashed`, severity: "fail", message: withoutAbsolutePaths(e instanceof Error ? e.message : String(e)), fix: "Fix the station or file an issue; it should never throw." });
-      continue;
+    // A station with variants (the panel) writes <station>-<variant>.packet.json for each.
+    for (const variant of judge.variants ? judge.variants(spec) : [undefined]) {
+      const base = variant ? `${judge.name}-${variant.id}` : judge.name;
+      let built;
+      try { built = buildPacket(judge, specPathArg, spec, draft, specSha, variant); }
+      catch (e) {
+        crashed.push({ station: judge.name, id: `judge-${judge.name}-crashed`, severity: "fail", message: withoutAbsolutePaths(e instanceof Error ? e.message : String(e)), fix: "Fix the station or file an issue; it should never throw." });
+        continue;
+      }
+      files.push({ station: judge.name, ...(variant ? { reader: variant.id } : {}), path: join(outDirArg, `${base}.packet.json`), bytes: built.packetBytes });
+      if (built.key) files.push({ station: judge.name, path: join(outDirArg, `${base}.key.json`), bytes: packetJson(built.key) });
     }
-    files.push({ station: judge.name, path: join(outDirArg, `${judge.name}.packet.json`), bytes: built.packetBytes });
-    if (built.key) files.push({ station: judge.name, path: join(outDirArg, `${judge.name}.key.json`), bytes: packetJson(built.key) });
   }
 
   const existing = files.filter((f) => existsSync(resolve(f.path))).map((f) => f.path);
@@ -203,7 +167,7 @@ export function prepareJudges(specPathArg, draftPathArg, outDirArg, { only, forc
     specPath: specPathArg,
     draftPath: draftPathArg,
     draftSha256: draft.sha256,
-    written: files.map((f) => ({ station: f.station, path: f.path })),
+    written: files.map((f) => ({ station: f.station, ...(f.reader ? { reader: f.reader } : {}), path: f.path })),
     skipped,
     crashed,
     code: crashed.length ? 1 : 0,
@@ -242,7 +206,11 @@ export function recordJudgment(packetPathArg, verdictPathArg) {
   const draft = readDraft(packet.draft);
   if (!draft) return { usage: true, error: `cannot read the packet's draft: ${packet.draft}` };
 
-  const base = { packetPath: packetPathArg, verdictPath: verdictPathArg, station: judge.name };
+  // A station with variants (the panel) names its variant in the packet; record rebuilds the packet
+  // for that variant, so the name is checked like every other byte of it.
+  const variantId = judge.variants ? judge.variantOf(packet) : undefined;
+  const variant = judge.variants ? judge.variants(spec).find((v) => v.id === variantId) : undefined;
+  const base = { packetPath: packetPathArg, verdictPath: verdictPathArg, station: judge.name, ...(judge.variants ? { reader: String(variantId ?? "") } : {}) };
   const t = toolsFor(judge.name, draft);
 
   // A verdict on bytes other than the ones the packet was prepared from judges nothing that exists.
@@ -259,9 +227,12 @@ export function recordJudgment(packetPathArg, verdictPathArg) {
   // the rebuilt copy only. A packet edited after prepare (its conditions, its inputs, a hash made to
   // match a changed draft) is refused here.
   const skip = judge.skipReason(spec, draft);
+  if (!skip && judge.variants && !variant) {
+    return { ...base, ok: false, invalid: true, findings: [t.finding("judge-packet-altered", `${packetPathArg} is for a ${judge.name} reader this spec does not name (${String(variantId ?? "none")})`, `judge prepare writes a ${judge.name} packet only for each reader the spec names; record verdicts only on packets prepare writes, and never edit one.`)], code: 1 };
+  }
   let rebuilt = null;
   if (!skip) {
-    try { rebuilt = buildPacket(judge, packet.spec, spec, draft, specSha); }
+    try { rebuilt = buildPacket(judge, packet.spec, spec, draft, specSha, variant); }
     catch (e) {
       return { ...base, ok: false, invalid: true, findings: [t.finding(`judge-${judge.name}-crashed`, withoutAbsolutePaths(e instanceof Error ? e.message : String(e)), "Fix the station or file an issue; it should never throw.")], code: 1 };
     }
@@ -337,7 +308,9 @@ export function recordJudgment(packetPathArg, verdictPathArg) {
     // rewords the instructions or the schema).
     const inputsSha = sha256(JSON.stringify(rebuilt.packet.inputs));
     const judgeLines = priorLines(ledger.priorText, "judge");
-    const prior = judgeLines.filter((l) => l.station === judge.name && l.draft === draftKey).at(-1);
+    // A panel reader's history is its own: the skeptic's line is compared with the skeptic's.
+    const sameReader = (l) => !judge.variants || l.reader === variant.id;
+    const prior = judgeLines.filter((l) => l.station === judge.name && sameReader(l) && l.draft === draftKey).at(-1);
     const last = prior ? { stations: { [prior.station]: prior.status }, draft_sha256: prior.draft_sha256, spec_sha256: prior.spec_sha256 } : undefined;
     // What changed since that line is judged by what the judge was shown: the packet. The draft
     // and the spec are named when their bytes changed. A packet that changed with both unchanged
@@ -362,13 +335,14 @@ export function recordJudgment(packetPathArg, verdictPathArg) {
     // one-shot means these bytes passed the first time they were judged, whatever the file was
     // called: bytes already judged under another path (a copy, a rename) never earn it.
     if (verdict === "one-shot") {
-      const sameBytes = judgeLines.filter((l) => l.station === judge.name && l.draft_sha256 === draft.sha256).at(-1);
+      const sameBytes = judgeLines.filter((l) => l.station === judge.name && sameReader(l) && l.draft_sha256 === draft.sha256).at(-1);
       if (sameBytes) { verdict = "not-improved"; verdictDetail = { reason: `these draft bytes were judged before as ${sameBytes.draft}: ${sameBytes.status}` }; }
     }
     const line = {
       at: new Date().toISOString(),
       kind: "judge",
       station: judge.name,
+      ...(judge.variants ? { reader: variant.id } : {}),
       draft: draftKey,
       draft_sha256: draft.sha256,
       spec_sha256: specSha,
@@ -382,5 +356,15 @@ export function recordJudgment(packetPathArg, verdictPathArg) {
     ledgerPath = ledger.decl;
   }
 
-  return { ...base, ok: true, status, ...(summary ? { summary } : {}), findings, verdict, verdictDetail, ledgerPath, ledgerWarning, code: status === "pass" ? 0 : 1 };
+  // A station whose verdict yields findings to answer (the panel) hands them to the triage file,
+  // beside the runs ledger, where `hyperspec triage` answers them and `check` holds them.
+  let triage = null;
+  let line = summary;
+  if (derived.triage) {
+    triage = addFindings(spec, derived.triage, { source: judge.name, reader: variant?.id ?? null, draftSha: draft.sha256, idPrefix: variant ? `${judge.name}-${variant.id}` : judge.name });
+    if (triage.warning) ledgerWarning = ledgerWarning ?? triage.warning;
+    else line = `${summary ? `${summary}; ` : ""}${triage.added} added to triage (${triage.decl})${triage.already ? `, ${triage.already} already there` : ""}`;
+  }
+
+  return { ...base, ok: true, status, ...(line ? { summary: line } : {}), findings, ...(triage && !triage.warning ? { triage: { path: triage.decl, added: triage.added, already: triage.already } } : {}), verdict, verdictDetail, ledgerPath, ledgerWarning, code: status === "pass" ? 0 : 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/sequence-draft.mjs

@@ -0,0 +1,75 @@
+// A work read in order often lives in several files (one per part, one per lesson). When a writing
+// spec lists them as writing.form.sequence.files, `hyperspec check <spec>` needs no --draft: the
+// draft is those files, joined in order. This module owns which files that is and how they join, so
+// lint (every entry must match a file) and check (the draft) agree on one reading.
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, posix, resolve } from "node:path";
+import { sha256 } from "./hash.mjs";
+import { str } from "./placeholder.mjs";
+import { splitLines } from "./draft.mjs";
+
+const list = (v) => (Array.isArray(v) ? v : []);
+const byNumber = (a, b) => a.localeCompare(b, "en", { numeric: true });
+
+// The declared entries, as written: writing.form.sequence.files, strings only.
+export function sequenceFilesDecl(spec) {
+  return list(spec?.data?.writing?.form?.sequence?.files).map(str).filter(Boolean);
+}
+
+// The files one entry names, relative to the spec's folder and written with "/": the entry itself
+// when it has no "*", or every file in its folder whose name matches, sorted so part-2 comes before
+// part-10. A "*" matches within a file name only; the folder part is taken literally. [] when
+// nothing matches.
+export function expandEntry(specDir, entry) {
+  const clean = entry.replace(/\\/g, "/");
+  const dir = posix.dirname(clean);
+  const base = posix.basename(clean);
+  const isFile = (rel) => { try { return statSync(resolve(specDir, rel)).isFile(); } catch { return false; } };
+  if (!base.includes("*")) return isFile(clean) ? [clean] : [];
+  const re = new RegExp(`^${base.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")}$`);
+  let names = [];
+  try { names = readdirSync(resolve(specDir, dir)); } catch { return []; }
+  return names.filter((n) => re.test(n)).sort(byNumber).map((n) => (dir === "." ? n : `${dir}/${n}`)).filter(isFile);
+}
+
+// Every file of the sequence in reading order, each once (at its first position).
+export function sequenceFiles(specDir, entries) {
+  const out = [];
+  for (const e of entries) for (const f of expandEntry(specDir, e)) if (!out.includes(f)) out.push(f);
+  return out;
+}
+
+// The draft `check` grades when the spec lists sequence files and no --draft is given:
+// { path, text, lines, sha256, sources }, the same shape src/draft.mjs's readDraft returns plus
+// sources, one per file: { file, at, startLine, lineCount }. file is the path relative to the spec
+// (what a finding names); at resolves from the working directory (what a station opens, such as
+// links resolving a relative link beside the file that holds it). Each file's YAML frontmatter is
+// blanked line for line, so its metadata is not prose and its line numbers stay its own. sha256
+// covers every file's name and bytes. path is the first file's. null when no file matches.
+export function readSequenceDraft(spec, specPathArg) {
+  const files = sequenceFiles(spec.dir, sequenceFilesDecl(spec));
+  if (!files.length) return null;
+  const parts = [];
+  const hashed = [];
+  const sources = [];
+  let startLine = 1;
+  for (const file of files) {
+    const buf = readFileSync(resolve(spec.dir, file));
+    hashed.push(Buffer.from(`${file}\n`), buf);
+    let text = buf.toString("utf8").replace(/^\uFEFF/, "");
+    text = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, (fm) => fm.replace(/[^\n]/g, ""));
+    if (!text.endsWith("\n")) text += "\n";
+    const lineCount = text.split("\n").length - 1;
+    sources.push({ file, at: join(dirname(specPathArg), file), startLine, lineCount });
+    parts.push(text);
+    startLine += lineCount;
+  }
+  const text = parts.join("");
+  return { path: sources[0].at, text, lines: splitLines(text), sha256: sha256(Buffer.concat(hashed)), sources };
+}
+
+// The source holding 1-based draft line `line`, or null.
+export function sourceAt(draft, line) {
+  return list(draft?.sources).find((s) => line >= s.startLine && line < s.startLine + s.lineCount) ?? null;
+}

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. 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";
@@ -13,6 +13,8 @@ import * as quotes from "./quotes.mjs";
 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 },
@@ -22,6 +24,8 @@ export const STATIONS = Object.freeze([
   { name: privateStation.name, run: privateStation.run },
   { 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));