@supersuit/hyperspec 0.8.0 → 0.9.1

package/bin/hyperspec.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, statSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { existsSync, statSync, writeFileSync, readFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname, resolve, join } from "node:path";
 import { loadSpec } from "../src/load.mjs";
 import { lintSpec } from "../src/rules.mjs";
@@ -12,13 +12,15 @@ import { approve } from "../src/writer.mjs";
 import { reproduce } from "../src/reproduce.mjs";
 import { regenerate } from "../src/regenerate.mjs";
 import { compare } from "../src/compare.mjs";
-import { splitSegments } from "../src/segments.mjs";
+import { splitSegments, carrySegments } from "../src/segments.mjs";
 import { sha256 } from "../src/hash.mjs";
 import { readScope, measureFeatures, writeFeatures, scopeTemplate, GOLDENS_README } from "../src/dna.mjs";
 import { str } from "../src/placeholder.mjs";
 import { runCheck } from "../src/check.mjs";
 import { prepareJudges, recordJudgment } from "../src/judge.mjs";
 import { prepareLearn, recordLearn, tallyLine } from "../src/learn.mjs";
+import { triageContext, triageState, answerFinding, importReview, replyText } from "../src/triage.mjs";
+import { sourceAt } from "../src/sequence-draft.mjs";
 
 const HELP = `hyperspec <command> [options]
 
@@ -51,7 +53,10 @@ const HELP = `hyperspec <command> [options]
                                persona (against the claims ledger), and for fiction attribution (a
                                blind speaker test on the dialogue lines whose speaker the draft
                                names; the answers go to attribution.key.json, likewise rebuilt)
-                               and knowledge (each character's knowledge timeline);
+                               and knowledge (each character's knowledge timeline), and panel
+                               (one panel-<reader>.packet.json per reader: writing.panel's, or a
+                               skeptic, a novice and an expert, and always the audience's reader
+                               as buyer);
                                the same spec and draft give byte-identical packets; refuses to
                                overwrite an existing packet without --force
                                exit 0 written, 1 a station could not build its packet (the rest
@@ -65,7 +70,28 @@ const HELP = `hyperspec <command> [options]
                                verdict appends nothing; run it from the folder prepare ran in, since
                                the packet keeps the spec and draft paths as they were given
                                exit 0 the station passed, 1 it failed or the verdict is invalid
-                               or stale, 2 usage
+                               or stale, 2 usage; a panel verdict's improve, missing and remove
+                               items go to triage.jsonl, beside the runs ledger
+  triage status <spec> [--draft <file>] [--json]
+                               count the answers in the spec's triage.jsonl, list the passages two
+                               or more readers share, and hold every answer to the draft (as
+                               check's triage station does); without --draft a spec that lists
+                               writing.form.sequence.files reads them, as check does
+                               exit 0 it would pass, 1 it would fail, 2 usage
+  triage answer <spec> <finding> taken|kept|already-true|open [--evidence S] [--reason S]
+                [--draft <file>] [--json]
+                               answer one finding: taken and already-true need --evidence, a
+                               passage of the draft word for word; kept needs --reason
+                               exit 0 written, 1 refused (nothing written), 2 usage
+  triage import <spec> <review> [--source S] [--draft <file>] [--json]
+                               bring an outside review (markdown or plain text) in as findings;
+                               a heading names the reader, Good/Improve/Missing/Remove labels set
+                               the kind, each list item is a finding, praise is counted only
+                               exit 0 imported, 1 the review holds nothing to answer, 2 usage
+  triage reply <spec> [--source S] [--draft <file>] [--json]
+                               print a plain-text reply to the reviewer from the answers; it
+                               never sends anything
+                               exit 0 ready to send, 1 a finding is still unanswered, 2 usage
   learn prepare <spec> --first <draft> --approved <draft> --out <dir> [--force] [--json]
                                needs a writing spec that passes lint (exits with lint's own code
                                otherwise); diffs the first draft a factory produced against the
@@ -99,16 +125,21 @@ const HELP = `hyperspec <command> [options]
                                writing, --kind with it (use --form), or a folder that does not
                                exist
 
-  segments init <material> --id <mid> [--out <file>] [--by paragraph|sentence]
+  segments init <material> --id <mid> [--out <file>] [--by paragraph|sentence] [--keep <old>]
                                split a material into candidate segments, written as JSONL to
                                <material>.segments.jsonl by default; every segment starts label:
                                unlabeled, never valid in lint; label each one by hand (claim,
                                story, quote, stance, question, aside, private), then run hyperspec
                                lint on the spec; --by sentence also starts a segment at each list
-                               item (-, *, +, 1. or 1) then a space); refuses to overwrite an
-                               existing file (exit 2); exit 2 for a missing material, a material
-                               with nothing in it, an --out folder that does not exist, or a --by
-                               outside paragraph/sentence
+                               item (-, *, +, 1. or 1) then a space); --keep re-marks an edited
+                               material: every segment whose text, trimmed, an old segment in
+                               <old> has keeps that segment's id, label and every other key, and
+                               the rest are listed to label; refuses to overwrite an existing
+                               file unless --keep names it (exit 2); exit 2 for a missing
+                               material, a material with nothing in it, an --out folder that does
+                               not exist, a --by outside paragraph/sentence, or a --keep file that
+                               cannot be read, has a line that is not a JSON object, or marks
+                               another material
 
   dna init <scope-dir> --writer W --form F --audience A --purpose P
                                write a new writer-DNA scope: scope.md (writer, form, audience,
@@ -199,7 +230,7 @@ if (cmd === "segments") {
   const sub = argv[1];
 
   if (sub === "init") {
-    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--id", "--out", "--by"] });
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--id", "--out", "--by", "--keep"] });
     if (parsed.error) { console.error(parsed.error); process.exit(2); }
     const [material] = parsed.positionals;
     if (!material) { console.error("segments init needs a material path"); process.exit(2); }
@@ -211,18 +242,55 @@ if (cmd === "segments") {
     try { materialStat = statSync(material); } catch { materialStat = null; }
     if (!materialStat || !materialStat.isFile()) { console.error(`material not found: ${material}`); process.exit(2); }
     const out = parsed.values["--out"] ?? `${material}.segments.jsonl`;
-    if (existsSync(out)) { console.error(`refusing to overwrite ${out}`); process.exit(2); }
+    const keep = parsed.values["--keep"];
+    // --keep may name the file being written: re-marking in place is the point. Nothing else is
+    // ever overwritten.
+    const samePath = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
+    if (existsSync(out) && !(keep && samePath(keep, out))) { console.error(`refusing to overwrite ${out}${keep ? " (--keep names a different file)" : ""}`); process.exit(2); }
     const outFolder = dirname(resolve(out));
     if (!existsSync(outFolder) || !statSync(outFolder).isDirectory()) { console.error(`folder does not exist: ${dirname(out)}; create it first`); process.exit(2); }
 
+    // The old segments to carry labels from: every line after the header, each a JSON object.
+    let old = null;
+    if (keep) {
+      let raw;
+      try { raw = readFileSync(keep, "utf8"); } catch { console.error(`--keep file not found: ${keep}`); process.exit(2); }
+      const rows = raw.split("\n").map((l, i) => ({ n: i + 1, l })).filter((r) => r.l.trim());
+      old = [];
+      for (const { n, l } of rows) {
+        let o;
+        try { o = JSON.parse(l); } catch { o = null; }
+        if (!o || typeof o !== "object" || Array.isArray(o)) { console.error(`--keep file ${keep} line ${n} is not a JSON object; fix it, or mark the material from scratch`); process.exit(2); }
+        if (n === 1) {
+          if (str(o.material) && str(o.material) !== id) { console.error(`--keep file ${keep} marks material "${o.material}", not "${id}"`); process.exit(2); }
+          continue;
+        }
+        old.push(o);
+      }
+    }
+
     const buf = readFileSync(material);
     const text = buf.toString("utf8");
     if (!/\S/.test(text)) { console.error(`nothing to mark: ${material} has no text`); process.exit(2); }
-    const segments = splitSegments(text, { by });
+    const fresh = splitSegments(text, { by });
+    const kept = old ? carrySegments(fresh, old) : null;
+    const segments = kept ? kept.segments : fresh;
     const header = { material: id, path: material, sha256: sha256(buf) };
     const lines = [JSON.stringify(header), ...segments.map((s) => JSON.stringify(s))];
     writeFileSync(out, `${lines.join("\n")}\n`);
-    console.log(`${segments.length} segments written to ${out}. Label every segment (claim, story, quote, stance, question, aside, private), then run hyperspec lint on the spec.`);
+    if (!kept) {
+      console.log(`${segments.length} segments written to ${out}. Label every segment (claim, story, quote, stance, question, aside, private), then run hyperspec lint on the spec.`);
+      process.exit(0);
+    }
+    const todo = kept.unlabeled;
+    console.log(`${segments.length} segments written to ${out}, ${kept.carried} labels carried from ${keep}, ${todo.length} to label${todo.length ? ":" : "."}`);
+    for (const s of todo) {
+      const t = s.text.replace(/\s+/g, " ").trim();
+      console.log(`  ${s.id} ${JSON.stringify(t.length > 60 ? `${t.slice(0, 60)}...` : t)}`);
+    }
+    console.log(todo.length
+      ? "Label each one (claim, story, quote, stance, question, aside, private), then run hyperspec lint on the spec."
+      : "Run hyperspec lint on the spec.");
     process.exit(0);
   }
 
@@ -521,6 +589,110 @@ if (cmd === "learn") {
   process.exit(2);
 }
 
+if (cmd === "triage") {
+  const sub = argv[1];
+  const flags = {
+    status: { valueFlags: ["--draft"], boolFlags: ["--json"] },
+    answer: { valueFlags: ["--draft", "--evidence", "--reason"], boolFlags: ["--json"] },
+    import: { valueFlags: ["--draft", "--source"], boolFlags: ["--json"] },
+    reply: { valueFlags: ["--draft", "--source"], boolFlags: ["--json"] },
+  }[sub];
+  if (!flags) { console.error(`unknown triage subcommand: ${sub ?? "(none)"}\n\n${HELP}`); process.exit(2); }
+  const parsed = parseArgs(argv.slice(2), flags);
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [specPath, ...rest] = parsed.positionals;
+  const json = parsed.values["--json"];
+  const usage = (error) => {
+    if (json) console.log(JSON.stringify({ spec: specPath ?? null, draft: parsed.values["--draft"] ?? null, error }, null, 2));
+    else console.error(error);
+    process.exit(2);
+  };
+  const ctx = triageContext(specPath, parsed.values["--draft"], `triage ${sub}`);
+  if (ctx.usage) usage(ctx.error);
+  const { spec, draft } = ctx;
+  // A finding's line, named the way check names it: the file and its own line for a sequence.
+  const where = (f) => {
+    if (typeof f.line !== "number") return "";
+    const src = sourceAt(draft, f.line);
+    return src ? ` (${src.file} line ${f.line - src.startLine + 1})` : ` (line ${f.line})`;
+  };
+  const printFinding = (f) => console.log(`  ${f.severity === "fail" ? "fail" : "warn"} [${f.id}] ${f.message}${where(f)}\n    fix: ${f.fix}`);
+
+  if (sub === "status") {
+    const state = triageState(spec, draft);
+    if (state.skip) {
+      if (json) console.log(JSON.stringify({ spec: specPath, status: "skip", reason: state.skip }, null, 2));
+      else console.log(`triage: skip (${state.skip})`);
+      process.exit(0);
+    }
+    const status = state.findings.some((f) => f.severity === "fail") ? "fail" : "pass";
+    if (json) console.log(JSON.stringify({ spec: specPath, path: state.decl, status, counts: state.counts, shared: state.shared, findings: state.findings, items: state.items }, null, 2));
+    else {
+      const c = state.counts;
+      console.log(`${state.decl}: ${state.items.length} finding${state.items.length === 1 ? "" : "s"}; ${c.taken} taken, ${c.kept} kept, ${c["already-true"]} already true, ${c.open} open, ${c.unanswered} not answered`);
+      if (state.shared.length) {
+        console.log("shared by two or more readers:");
+        for (const g of state.shared) {
+          const line = where({ line: g.line }).replace(/^ \((.*)\)$/, "$1");
+          console.log(`  ${line}: "${g.passage}"`);
+          for (const f of g.findings) console.log(`    ${f.reader} (${f.kind}): ${f.text}`);
+        }
+      }
+      console.log(`triage: ${status}`);
+      for (const f of state.findings) printFinding(f);
+    }
+    process.exit(status === "pass" ? 0 : 1);
+  }
+
+  if (sub === "answer") {
+    const [findingId, disposition] = rest;
+    if (!findingId) usage("triage answer needs a finding id");
+    if (!disposition) usage("triage answer needs a disposition: taken, kept, already-true or open");
+    const result = answerFinding(spec, draft, findingId, disposition, { evidence: parsed.values["--evidence"], reason: parsed.values["--reason"] });
+    if (result.usage) usage(result.error);
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else if (result.invalid) {
+      console.log(`${findingId}: answer refused, nothing written`);
+      for (const f of result.findings) printFinding(f);
+    } else console.log(`${findingId}: ${disposition} (${result.path})`);
+    process.exit(result.code);
+  }
+
+  if (sub === "import") {
+    const [reviewPath] = rest;
+    if (!reviewPath) usage("triage import needs a review file");
+    let text;
+    try { text = readFileSync(resolve(reviewPath), "utf8"); } catch { usage(`cannot read review: ${reviewPath}`); }
+    const source = parsed.values["--source"] ?? reviewPath;
+    const result = importReview(spec, draft, text, source);
+    if (result.usage) usage(result.error);
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else if (result.invalid) {
+      console.log(`${reviewPath}: nothing imported`);
+      for (const f of result.findings) printFinding(f);
+    } else {
+      console.log(`${source}: ${result.added} finding${result.added === 1 ? "" : "s"} added to triage (${result.path})${result.already ? `, ${result.already} already there` : ""}${result.praise ? `; ${result.praise} item${result.praise === 1 ? "" : "s"} of praise, not triaged` : ""}`);
+      for (const f of result.warnings) printFinding(f);
+    }
+    process.exit(result.code);
+  }
+
+  if (sub === "reply") {
+    const state = triageState(spec, draft);
+    if (state.skip) usage(`nothing to reply to: ${state.skip}`);
+    const source = parsed.values["--source"];
+    const reply = replyText(state.items, source);
+    if (!reply.count) usage(`no finding in ${state.decl} comes from ${source}`);
+    const failing = state.findings.filter((f) => f.severity === "fail");
+    if (json) console.log(JSON.stringify({ spec: specPath, source: source ?? null, text: reply.text, unanswered: reply.unanswered, ready: !failing.length }, null, 2));
+    else {
+      process.stdout.write(reply.text);
+      if (failing.length) console.error(`not ready to send: triage fails (${failing.length} finding${failing.length === 1 ? "" : "s"}); run hyperspec triage status`);
+    }
+    process.exit(failing.length ? 1 : 0);
+  }
+}
+
 // A spec that does not lint clean: print what lint would, say nothing was written, and exit with
 // lint's own code. Shared by judge prepare and learn prepare.
 function printLintBlocked(result, json, nothingWritten) {

package/examples/writing/course/part-1.md

@@ -42,6 +42,23 @@ Add a spoon of starter to the dough from Lesson 1 and leave it somewhere warm. T
 
 **Try this:** start a starter today, and mark the jar with tape at its height after each feed.
 
+## Check yourself: Part 1
+
+1. *(Lesson 1)* Five hundred grams of flour and four hundred of water: what is the hydration?
+   - a) Forty percent
+   - b) Eighty percent
+2. *(Lesson 1)* When is flour and water a dough?
+   - a) When no dry flour is left
+   - b) When it has doubled
+3. *(Lesson 2)* What does a starter need every day?
+   - a) A pinch of salt
+   - b) A feed of flour and water
+4. *(Lesson 2)* How do you tell a proof is done?
+   - a) A finger dent fills back slowly
+   - b) The top has cracked
+
+**Answers:** 1 b · 2 a · 3 b · 4 a
+
 ---
 
 **Next, Part 2: The bake.** Shaping a loaf that holds itself up, and what happens to the crumb in the oven.

package/examples/writing/course/part-2.md

@@ -38,3 +38,20 @@ Heat the oven as hot as it goes, with a heavy pot inside. Put the loaf in the po
 Let it cool for an hour before you cut it. Then read the crumb. Big uneven holes mean a well proofed, high hydration dough. A tight, even crumb with a dense band at the bottom means the proof was too short.
 
 **Try this:** cut the two loaves from Lesson 3 and compare their crumb.
+
+## Check yourself: Part 2
+
+1. *(Lesson 3)* Why give a dough a bench rest?
+   - a) So it relaxes enough to be shaped again
+   - b) So it cools down
+2. *(Lesson 3)* What lets a shaped loaf stand instead of spreading?
+   - a) More water
+   - b) Surface tension
+3. *(Lesson 4)* When does oven spring happen?
+   - a) In the first ten minutes of heat
+   - b) While the loaf cools
+4. *(Lesson 4)* A tight, even crumb with a dense band at the bottom means what?
+   - a) The oven was too hot
+   - b) The proof was too short
+
+**Answers:** 1 a · 2 b · 3 a · 4 b

package/examples/writing/course.hyperspec.md

@@ -160,6 +160,7 @@ writing:
       terms_section: New terms
       outline: course/outline.md
       teaser: Next,
+      quiz: Check yourself
     check:
       station: structure and length, then the sequence station
     source: form decision

package/examples/writing/essay/judge/panel-buyer.packet.json

@@ -0,0 +1,118 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "panel",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "simulated reader reports where it got lost and where it stopped reading",
+  "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.",
+  "inputs": {
+    "reader": {
+      "id": "buyer",
+      "who": "someone in their first three months of managing, who was promoted from the team they now lead",
+      "knows": [
+        "one-on-one",
+        "report",
+        "tracker"
+      ],
+      "lens": "what they want from this piece: a plan for the first meeting that will not waste either person's half hour"
+    },
+    "draft": "# Hand your first one-on-one to the person you manage\n\n## Who sets the agenda\n\nYour first one-on-one with a new report is the only meeting on your calendar where they should\nset the agenda. Everything else you run. This one you hand over.\n\nIf you walk in with a list, you have told your report what the meeting is for, and it is for\nyou. They will answer your list politely and leave. You will know nothing you did not know when\nyou sat down, and so will they.\n\nMy team ran a [survey](materials/team-survey.md) this spring. 29 of 41 people said their most useful one-on-one in the last\nquarter was one where they brought the first topic. The meeting that worked for them was the one\nthey started.\n\nSo give them the start. The simplest way to do it is a running agenda: one shared document per\nperson, kept for as long as you manage them. Your report adds items before each meeting, and you\nadd yours last, at the bottom. That is how an engineering manager I interviewed, eight years into\nthe job, runs hers. Her rule is short: the report owns the agenda.\n\n## My first one-on-one\n\nMy first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a\nlist, and I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes\nlater my report said thanks and left, and I had learned nothing I could not have read in the\ntracker.\n\nWhat I ran was a status meeting, which is a meeting spent reading out loud what the tracker\nalready says. Your report wrote those updates. Asking them to recite the updates to you teaches\nyou nothing new, and it spends the one half hour a week that belongs to them.\n\nThe survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the\nlast quarter was mostly project status. Read the tracker before you walk in, and leave status\nthere.\n\n## The three questions\n\nHere is what I ask now, in this order, and then I let the report take over:\n\n1. What is taking more of your energy than it should?\n2. What do you want to be doing more of in six months?\n3. What should I stop doing, or start doing, that would make your week easier?\n\nThree is enough to hand the meeting over. The first asks about this week. The second asks about\nthe next six months. The third asks about you, and it is the one your report will not raise\nwithout being asked. A fourth question starts to look like your list again, and the list is what\nyou came to give up.\n\nAsk them in the same words every time. Your report will learn them, and after a few weeks they\nwill walk in with answers already half formed. That is the point of fixing the words: the meeting\nstarts on their topic before you have said anything at all.\n\nThe second question is the one my own team asked for. The most common free-text request in the\nsurvey, in 9 responses, was to be asked what they want to work on next.\n\nAfter the third question, stop talking.\n\n## What to do with the answers\n\nWait after each question, longer than you want to. Dana, the engineering manager I interviewed,\nputs it in three short sentences: \"Wait. Count to five. The real answer is the second one.\" The first\nanswer your report gives is the tidy one, the version they could give anyone. The second is what\nthey came in with, and you only hear it if you let the silence run.\n\nWrite down what they say, in their words, at the top of the running agenda. That list is where\nyour next one-on-one starts, so the meeting stays theirs the week after too.\n\nDo not try to fix everything in the room. Pick one thing you can act on this week, say what you\nwill do, and do it before you meet again. The rest stays on the running agenda until it is done\nor your report takes it off.\n\nAnd keep your own urgent items out of it. She told me: \"If I have something urgent, it is not a\none-on-one topic. I send it the day it happens.\" Your report should never have to wait a week to\nhear something you needed them to know on Monday.\n\n## Before the meeting\n\nOpen the invite and delete your list from it. Ask your report to add the first item to the\nrunning agenda instead.\n\nSo write the three questions on a card. Ask the first one. Then wait, longer than feels polite,\nbecause the first answer is the one they rehearsed and the second one is the one you came for.\n"
+  },
+  "verdict_schema": {
+    "type": "object",
+    "required": [
+      "good",
+      "improve",
+      "missing",
+      "remove"
+    ],
+    "properties": {
+      "good": {
+        "type": "array",
+        "description": "what works for this reader; empty when nothing does",
+        "items": {
+          "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"
+            }
+          }
+        }
+      },
+      "improve": {
+        "type": "array",
+        "description": "what should change",
+        "items": {
+          "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"
+            }
+          }
+        }
+      },
+      "missing": {
+        "type": "array",
+        "description": "what this reader needs that the draft does not give",
+        "items": {
+          "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"
+            }
+          }
+        }
+      },
+      "remove": {
+        "type": "array",
+        "description": "what should go",
+        "items": {
+          "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"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/examples/writing/essay/judge/panel-expert.packet.json

@@ -0,0 +1,114 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "panel",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "simulated reader reports where it got lost and where it stopped reading",
+  "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.",
+  "inputs": {
+    "reader": {
+      "id": "expert",
+      "who": "an expert in the piece's subject",
+      "knows": [],
+      "lens": "what is wrong, out of date, oversimplified or missing for someone who knows the field"
+    },
+    "draft": "# Hand your first one-on-one to the person you manage\n\n## Who sets the agenda\n\nYour first one-on-one with a new report is the only meeting on your calendar where they should\nset the agenda. Everything else you run. This one you hand over.\n\nIf you walk in with a list, you have told your report what the meeting is for, and it is for\nyou. They will answer your list politely and leave. You will know nothing you did not know when\nyou sat down, and so will they.\n\nMy team ran a [survey](materials/team-survey.md) this spring. 29 of 41 people said their most useful one-on-one in the last\nquarter was one where they brought the first topic. The meeting that worked for them was the one\nthey started.\n\nSo give them the start. The simplest way to do it is a running agenda: one shared document per\nperson, kept for as long as you manage them. Your report adds items before each meeting, and you\nadd yours last, at the bottom. That is how an engineering manager I interviewed, eight years into\nthe job, runs hers. Her rule is short: the report owns the agenda.\n\n## My first one-on-one\n\nMy first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a\nlist, and I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes\nlater my report said thanks and left, and I had learned nothing I could not have read in the\ntracker.\n\nWhat I ran was a status meeting, which is a meeting spent reading out loud what the tracker\nalready says. Your report wrote those updates. Asking them to recite the updates to you teaches\nyou nothing new, and it spends the one half hour a week that belongs to them.\n\nThe survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the\nlast quarter was mostly project status. Read the tracker before you walk in, and leave status\nthere.\n\n## The three questions\n\nHere is what I ask now, in this order, and then I let the report take over:\n\n1. What is taking more of your energy than it should?\n2. What do you want to be doing more of in six months?\n3. What should I stop doing, or start doing, that would make your week easier?\n\nThree is enough to hand the meeting over. The first asks about this week. The second asks about\nthe next six months. The third asks about you, and it is the one your report will not raise\nwithout being asked. A fourth question starts to look like your list again, and the list is what\nyou came to give up.\n\nAsk them in the same words every time. Your report will learn them, and after a few weeks they\nwill walk in with answers already half formed. That is the point of fixing the words: the meeting\nstarts on their topic before you have said anything at all.\n\nThe second question is the one my own team asked for. The most common free-text request in the\nsurvey, in 9 responses, was to be asked what they want to work on next.\n\nAfter the third question, stop talking.\n\n## What to do with the answers\n\nWait after each question, longer than you want to. Dana, the engineering manager I interviewed,\nputs it in three short sentences: \"Wait. Count to five. The real answer is the second one.\" The first\nanswer your report gives is the tidy one, the version they could give anyone. The second is what\nthey came in with, and you only hear it if you let the silence run.\n\nWrite down what they say, in their words, at the top of the running agenda. That list is where\nyour next one-on-one starts, so the meeting stays theirs the week after too.\n\nDo not try to fix everything in the room. Pick one thing you can act on this week, say what you\nwill do, and do it before you meet again. The rest stays on the running agenda until it is done\nor your report takes it off.\n\nAnd keep your own urgent items out of it. She told me: \"If I have something urgent, it is not a\none-on-one topic. I send it the day it happens.\" Your report should never have to wait a week to\nhear something you needed them to know on Monday.\n\n## Before the meeting\n\nOpen the invite and delete your list from it. Ask your report to add the first item to the\nrunning agenda instead.\n\nSo write the three questions on a card. Ask the first one. Then wait, longer than feels polite,\nbecause the first answer is the one they rehearsed and the second one is the one you came for.\n"
+  },
+  "verdict_schema": {
+    "type": "object",
+    "required": [
+      "good",
+      "improve",
+      "missing",
+      "remove"
+    ],
+    "properties": {
+      "good": {
+        "type": "array",
+        "description": "what works for this reader; empty when nothing does",
+        "items": {
+          "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"
+            }
+          }
+        }
+      },
+      "improve": {
+        "type": "array",
+        "description": "what should change",
+        "items": {
+          "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"
+            }
+          }
+        }
+      },
+      "missing": {
+        "type": "array",
+        "description": "what this reader needs that the draft does not give",
+        "items": {
+          "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"
+            }
+          }
+        }
+      },
+      "remove": {
+        "type": "array",
+        "description": "what should go",
+        "items": {
+          "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"
+            }
+          }
+        }
+      }
+    }
+  }
+}