@supersuit/hyperspec 0.5.0 → 0.7.0

package/bin/hyperspec.mjs

@@ -16,11 +16,74 @@ import { splitSegments } 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";
 
 const HELP = `hyperspec <command> [options]
 
   lint <file...> [--json]      score each hyperspec against the nine tests
                                exit 0 pass, 1 a test fails, 3 blocked on an open decision, 2 usage
+  check <spec> --draft <file> [--json] [--only a,b]
+                               needs a writing spec (profile: writing); lints it first (a spec
+                               that does not pass lint, or is blocked, exits with lint's own code
+                               and runs no station: a draft cannot be checked against a spec that
+                               is not ready); then runs every deterministic station (or the
+                               --only subset, by name) against the draft, printing pass, fail
+                               (with findings) or skip (with a reason) per station; appends one
+                               line to the spec's improvement.ledger with a verdict: one-shot,
+                               improved, or not-improved with a reason (an --only run is partial:
+                               not-improved, and ignored by later verdicts)
+                               exit 0 every run station passed, 1 a station failed, 2 usage
+                               (including a missing draft file, a spec without the writing
+                               profile, or an --only that names no known station)
+  judge prepare <spec> --draft <file> --out <dir> [--only a,b] [--force] [--json]
+                               needs a writing spec that passes lint (exits with lint's own code
+                               otherwise); writes one <station>.packet.json per applicable
+                               judgment station (or the --only subset) into <dir>: the rubric from
+                               the spec, fixed instructions, the inputs and the exact verdict
+                               shape, for an outside judge to fill; hyperspec never calls a model;
+                               stations: doctor, lineup (a blind voice lineup against the DNA
+                               scope's goldens, whose answer goes to lineup.key.json for a person
+                               to read; record rebuilds it and never reads the file), reader,
+                               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);
+                               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
+                               are written), 2 usage (a missing or non-folder --out, an existing
+                               packet without --force, an unknown --only name), or lint's own code
+  judge record <packet> --verdict <file> [--json]
+                               validate the judge's verdict against its packet (every evidence
+                               span must appear in the draft; a draft or spec changed since the
+                               packet is stale), derive the station's status, and append one line
+                               to the spec's improvement.ledger, as check does; an invalid or stale
+                               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
+  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
+                               draft a person approved, sentence by sentence, and writes
+                               <dir>/learn.packet.json: each edit as a hunk (E1..En: deleted,
+                               inserted or replaced, with both texts), the spec's block names plus
+                               none, fixed instructions and the verdict shape, for an outside judge
+                               to name the block that should have prevented each edit; the same
+                               files give a byte-identical packet; refuses to overwrite it without
+                               --force
+                               exit 0 written, 2 usage
+  learn record <packet> --verdict <file> [--json]
+                               rebuild the packet from the files on disk (a changed file is stale,
+                               an edited packet is refused), validate the verdict (every hunk id
+                               exactly once, a block the spec has or none, a why), print the edits
+                               per block and one next move for the block with the most, and append
+                               one learn line to the spec's improvement.ledger (not-improved: the
+                               spec has not changed yet); learn never edits the spec
+                               exit 0 recorded, 1 the verdict is invalid or stale (nothing
+                               appended), 2 usage
   init <file> [--title T] [--kind K]   write a new hyperspec skeleton (refuses to overwrite)
   init <file> --profile writing [--title T] [--form F] [--fiction]
                                write a writing-profile skeleton: every required block (materials,
@@ -282,6 +345,195 @@ if (cmd === "lint") {
   process.exit(worst);
 }
 
+if (cmd === "check") {
+  const parsed = parseArgs(argv.slice(1), { valueFlags: ["--draft", "--only"], boolFlags: ["--json"] });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [specPath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  // A usage error exits 2: a plain message on stderr, or under --json one document on stdout,
+  // { spec, draft, error }, the way lint --json reports a file it could not read.
+  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);
+  };
+  if (!specPath) usage("check needs a spec path");
+  if (!parsed.values["--draft"]) usage("check needs --draft <file>");
+  let only;
+  if (parsed.values["--only"] !== undefined) {
+    only = parsed.values["--only"].split(",").map((s) => s.trim()).filter(Boolean);
+    if (!only.length) usage("--only names no station");
+  }
+
+  const result = runCheck(specPath, parsed.values["--draft"], { only });
+
+  // Usage errors (an unreadable spec, a spec without the writing profile, an unknown --only name,
+  // a missing draft file): exit 2, as above.
+  if (result.usage) usage(result.error);
+
+  if (result.lintBlocked) {
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else {
+      const r = result.lintScore;
+      console.log(`${result.specPath}: ${r.status} (${r.passed}/9)${r.open.length ? `, open: ${r.open.join(", ")}` : ""}`);
+      for (const t of r.tests) if (!t.pass) console.log(`  ✗ ${t.n}. ${t.name}`);
+      for (const f of result.lintFindings) console.log(`    ${f.severity === "fail" ? "fail" : "warn"} [${f.test}] ${f.message}\n         fix: ${f.fix}`);
+      console.log("no stations run: the spec is not ready (run `hyperspec lint` on it for details)");
+    }
+    process.exit(result.code);
+  }
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    for (const s of result.stations) {
+      if (s.status === "skip") { console.log(`${s.station}: skip (${s.reason})`); continue; }
+      console.log(`${s.station}: ${s.status}`);
+      for (const finding of s.findings) console.log(`  ${finding.severity === "fail" ? "fail" : "warn"} [${finding.id}] ${finding.message}${typeof finding.line === "number" ? ` (line ${finding.line})` : ""}\n    fix: ${finding.fix}`);
+    }
+    if (result.verdict) {
+      const detail = result.verdictDetail.change ?? result.verdictDetail.reason;
+      console.log(`verdict: ${result.verdict}${detail ? ` (${detail})` : ""}`);
+    }
+    if (result.ledgerWarning) console.log(`warn: ${result.ledgerWarning}`);
+  }
+  process.exit(result.code);
+}
+
+if (cmd === "judge") {
+  const sub = argv[1];
+  const printFinding = (f) => console.log(`  ${f.severity === "fail" ? "fail" : "warn"} [${f.id}] ${f.message}${typeof f.line === "number" ? ` (line ${f.line})` : ""}\n    fix: ${f.fix}`);
+
+  if (sub === "prepare") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--draft", "--out", "--only"], boolFlags: ["--force", "--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [specPath] = parsed.positionals;
+    const json = parsed.values["--json"];
+    const usage = (error) => {
+      if (json) console.log(JSON.stringify({ spec: specPath ?? null, draft: parsed.values["--draft"] ?? null, out: parsed.values["--out"] ?? null, error }, null, 2));
+      else console.error(error);
+      process.exit(2);
+    };
+    if (!specPath) usage("judge prepare needs a spec path");
+    if (!parsed.values["--draft"]) usage("judge prepare needs --draft <file>");
+    if (!parsed.values["--out"]) usage("judge prepare needs --out <dir>");
+    let only;
+    if (parsed.values["--only"] !== undefined) {
+      only = parsed.values["--only"].split(",").map((x) => x.trim()).filter(Boolean);
+      if (!only.length) usage("--only names no judge");
+    }
+    const result = prepareJudges(specPath, parsed.values["--draft"], parsed.values["--out"], { only, force: parsed.values["--force"] });
+    if (result.usage) usage(result.error);
+    if (result.lintBlocked) printLintBlocked(result, json, "no packets written");
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else {
+      for (const w of result.written) console.log(w.path);
+      for (const s of result.skipped) console.log(`${s.station}: skip (${s.reason})`);
+      for (const f of result.crashed) { console.log(`${f.station}: no packet`); printFinding(f); }
+    }
+    process.exit(result.code);
+  }
+
+  if (sub === "record") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--verdict"], boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [packetPath] = parsed.positionals;
+    const json = parsed.values["--json"];
+    const usage = (error) => {
+      if (json) console.log(JSON.stringify({ packet: packetPath ?? null, verdict: parsed.values["--verdict"] ?? null, error }, null, 2));
+      else console.error(error);
+      process.exit(2);
+    };
+    if (!packetPath) usage("judge record needs a packet path");
+    if (!parsed.values["--verdict"]) usage("judge record needs --verdict <file>");
+    const result = recordJudgment(packetPath, parsed.values["--verdict"]);
+    if (result.usage) usage(result.error);
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else if (result.invalid) {
+      console.log(`${result.station}: ${result.stale ? "stale packet" : "invalid verdict"}, nothing recorded`);
+      for (const f of result.findings) printFinding(f);
+    } else {
+      console.log(`${result.station}: ${result.status}`);
+      if (result.summary) console.log(`  ${result.summary}`);
+      for (const f of result.findings) printFinding(f);
+      if (result.verdict) {
+        const detail = result.verdictDetail.change ?? result.verdictDetail.reason;
+        console.log(`verdict: ${result.verdict}${detail ? ` (${detail})` : ""}`);
+      }
+      if (result.ledgerWarning) console.log(`warn: ${result.ledgerWarning}`);
+    }
+    process.exit(result.code);
+  }
+
+  console.error(`unknown judge subcommand: ${sub ?? "(none)"}\n\n${HELP}`);
+  process.exit(2);
+}
+
+if (cmd === "learn") {
+  const sub = argv[1];
+  const printFinding = (f) => console.log(`  ${f.severity === "fail" ? "fail" : "warn"} [${f.id}] ${f.message}\n    fix: ${f.fix}`);
+
+  if (sub === "prepare") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--first", "--approved", "--out"], boolFlags: ["--force", "--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [specPath] = parsed.positionals;
+    const json = parsed.values["--json"];
+    const opts = { first: parsed.values["--first"], approved: parsed.values["--approved"], out: parsed.values["--out"], force: parsed.values["--force"] };
+    const result = prepareLearn(specPath, opts);
+    if (result.usage) {
+      if (json) console.log(JSON.stringify({ spec: specPath ?? null, first: opts.first ?? null, approved: opts.approved ?? null, out: opts.out ?? null, error: result.error }, null, 2));
+      else console.error(result.error);
+      process.exit(2);
+    }
+    if (result.lintBlocked) printLintBlocked(result, json, "no packet written");
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`${result.path}\n${result.summary}`);
+    process.exit(result.code);
+  }
+
+  if (sub === "record") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--verdict"], boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [packetPath] = parsed.positionals;
+    const json = parsed.values["--json"];
+    const result = recordLearn(packetPath, parsed.values["--verdict"]);
+    if (result.usage) {
+      if (json) console.log(JSON.stringify({ packet: packetPath ?? null, verdict: parsed.values["--verdict"] ?? null, error: result.error }, null, 2));
+      else console.error(result.error);
+      process.exit(2);
+    }
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else if (result.invalid) {
+      console.log(`learn: ${result.stale ? "stale packet" : "invalid verdict"}, nothing recorded`);
+      for (const f of result.findings) printFinding(f);
+    } else {
+      console.log(`learn: ${result.edits} edit${result.edits === 1 ? "" : "s"} classified`);
+      for (const [block, c] of Object.entries(result.tally)) console.log(`  ${block} ${tallyLine(c)}`);
+      console.log(`next move: ${result.next}`);
+      if (result.verdict) console.log(`verdict: ${result.verdict} (${result.reason})`);
+      if (result.ledgerWarning) console.log(`warn: ${result.ledgerWarning}`);
+    }
+    process.exit(result.code);
+  }
+
+  console.error(`unknown learn subcommand: ${sub ?? "(none)"}\n\n${HELP}`);
+  process.exit(2);
+}
+
+// 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) {
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else {
+    const r = result.lintScore;
+    console.log(`${result.specPath}: ${r.status} (${r.passed}/9)${r.open.length ? `, open: ${r.open.join(", ")}` : ""}`);
+    for (const t of r.tests) if (!t.pass) console.log(`  ✗ ${t.n}. ${t.name}`);
+    for (const f of result.lintFindings) console.log(`    ${f.severity === "fail" ? "fail" : "warn"} [${f.test}] ${f.message}\n         fix: ${f.fix}`);
+    console.log(`${nothingWritten}: the spec is not ready (run \`hyperspec lint\` on it for details)`);
+  }
+  process.exit(result.code);
+}
+
 // Generic flag/positional parser for the recipe verbs below. A value-taking flag (valueFlags,
 // repeatableFlags) never swallows a following --flag as its value (missing value is an error, not
 // a silent grab); a bool flag never eats the next token as a positional; any --flag not declared

package/examples/writing/essay/claims.jsonl

@@ -0,0 +1,9 @@
+{"text":"29 of 41 people said their most useful one-on-one in the last quarter was one where they brought the first topic.","source":"survey#s3","span":"29 of 41 said their most useful one-on-one in the last quarter was one where they brought the first topic."}
+{"text":"That is how an engineering manager I interviewed, eight years into the job, runs hers.","source":"interview#s4","span":"She keeps a shared document per person; they add items before the meeting, and she adds hers last, at the bottom."}
+{"text":"Her rule is short: the report owns the agenda.","source":"interview#s3","span":"Her rule: the report owns the agenda."}
+{"text":"My first one-on-one as a manager was a disaster, and the reason was simple: I ran it.","source":"voice-memo#s2","span":"My first one-on-one as a manager was a disaster, and the reason was simple: I ran it."}
+{"text":"11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status.","source":"survey#s4","span":"11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status."}
+{"text":"What is taking more of your energy than it should?","source":"voice-memo#s4","span":"What is taking more of your energy than it should?"}
+{"text":"What do you want to be doing more of in six months?","source":"voice-memo#s4","span":"What do you want to be doing more of in six months?"}
+{"text":"What should I stop doing, or start doing, that would make your week easier?","source":"voice-memo#s4","span":"What should I stop doing, or start doing, that would make your week easier?"}
+{"text":"The most common free-text request in the survey, in 9 responses, was to be asked what they want to work on next.","source":"survey#s5","span":"The most common free-text request, in 9 responses: \"ask me what I want to work on next.\""}

package/examples/writing/essay/draft.md

@@ -0,0 +1,82 @@
+# Hand your first one-on-one to the person you manage
+
+## Who sets the agenda
+
+Your first one-on-one with a new report is the only meeting on your calendar where they should
+set the agenda. Everything else you run. This one you hand over.
+
+If you walk in with a list, you have told your report what the meeting is for, and it is for
+you. They will answer your list politely and leave. You will know nothing you did not know when
+you sat down, and so will they.
+
+My team ran a [survey](materials/team-survey.md) this spring. 29 of 41 people said their most useful one-on-one in the last
+quarter was one where they brought the first topic. The meeting that worked for them was the one
+they started.
+
+So give them the start. The simplest way to do it is a running agenda: one shared document per
+person, kept for as long as you manage them. Your report adds items before each meeting, and you
+add yours last, at the bottom. That is how an engineering manager I interviewed, eight years into
+the job, runs hers. Her rule is short: the report owns the agenda.
+
+## My first one-on-one
+
+My first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a
+list, and I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes
+later my report said thanks and left, and I had learned nothing I could not have read in the
+tracker.
+
+What I ran was a status meeting, which is a meeting spent reading out loud what the tracker
+already says. Your report wrote those updates. Asking them to recite the updates to you teaches
+you nothing new, and it spends the one half hour a week that belongs to them.
+
+The survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the
+last quarter was mostly project status. Read the tracker before you walk in, and leave status
+there.
+
+## The three questions
+
+Here is what I ask now, in this order, and then I let the report take over:
+
+1. What is taking more of your energy than it should?
+2. What do you want to be doing more of in six months?
+3. What should I stop doing, or start doing, that would make your week easier?
+
+Three is enough to hand the meeting over. The first asks about this week. The second asks about
+the next six months. The third asks about you, and it is the one your report will not raise
+without being asked. A fourth question starts to look like your list again, and the list is what
+you came to give up.
+
+Ask them in the same words every time. Your report will learn them, and after a few weeks they
+will walk in with answers already half formed. That is the point of fixing the words: the meeting
+starts on their topic before you have said anything at all.
+
+The second question is the one my own team asked for. The most common free-text request in the
+survey, in 9 responses, was to be asked what they want to work on next.
+
+After the third question, stop talking.
+
+## What to do with the answers
+
+Wait after each question, longer than you want to. Dana, the engineering manager I interviewed,
+puts it in three short sentences: "Wait. Count to five. The real answer is the second one." The first
+answer your report gives is the tidy one, the version they could give anyone. The second is what
+they came in with, and you only hear it if you let the silence run.
+
+Write down what they say, in their words, at the top of the running agenda. That list is where
+your next one-on-one starts, so the meeting stays theirs the week after too.
+
+Do not try to fix everything in the room. Pick one thing you can act on this week, say what you
+will do, and do it before you meet again. The rest stays on the running agenda until it is done
+or your report takes it off.
+
+And keep your own urgent items out of it. She told me: "If I have something urgent, it is not a
+one-on-one topic. I send it the day it happens." Your report should never have to wait a week to
+hear something you needed them to know on Monday.
+
+## Before the meeting
+
+Open the invite and delete your list from it. Ask your report to add the first item to the
+running agenda instead.
+
+So write the three questions on a card. Ask the first one. Then wait, longer than feels polite,
+because the first answer is the one they rehearsed and the second one is the one you came for.

package/examples/writing/essay/judge/doctor.packet.json

@@ -0,0 +1,108 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "doctor",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "the doctor grades the draft against every condition; the simulated reader is asked whether it would copy the questions now",
+  "instructions": "Grade the draft (inputs.draft) against each condition in inputs.conditions: a condition passes unless the draft does what its fails_when describes. For every judgment, quote the draft as evidence: each evidence field is a span copied verbatim from inputs.draft. Then answer whether this reader, having read the draft, would take the next step (inputs.goal.next_if_worked) now, and quote the passage that decided it. Answer only in the verdict shape given in verdict_schema: one entry per condition id, each exactly once, with pass and would_take_next_step as true or false, and a note saying why for every condition that fails.",
+  "inputs": {
+    "goal": {
+      "from": "plans to run the first one-on-one from their own list",
+      "to": "hands the first one-on-one to the report and asks the three questions",
+      "next_if_worked": "writes the three questions on a card before the meeting",
+      "change": {
+        "kind": "action",
+        "text": "the reader asks the three questions in their next one-on-one and waits after each"
+      }
+    },
+    "conditions": [
+      {
+        "id": "r1",
+        "text": "the opening line tells the reader who sets the agenda of a first one-on-one",
+        "fails_when": "a reader shown only the first two sentences cannot say who should set the agenda"
+      },
+      {
+        "id": "r2",
+        "text": "the three questions appear word for word as the voice memo states them",
+        "fails_when": "any of the three questions differs from essay/materials/voice-memo.md by a word"
+      },
+      {
+        "id": "r3",
+        "text": "every survey figure in the draft matches the verified survey summary",
+        "fails_when": "a figure in the draft has no entry in the claims ledger pointing at essay/materials/team-survey.md, or differs from it"
+      },
+      {
+        "id": "r4",
+        "text": "the draft argues only the four claims in the spine, in order",
+        "fails_when": "a paragraph advances a point that traces to none of c1 to c4, or c3 lands before c2"
+      },
+      {
+        "id": "r5",
+        "text": "the draft tells the reader what to do with silence in the meeting",
+        "fails_when": "the draft never says to wait after asking a question"
+      },
+      {
+        "id": "r6",
+        "text": "the draft stays inside its length envelope",
+        "fails_when": "the word count is under 700 or over 1,100"
+      }
+    ],
+    "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": [
+      "conditions",
+      "would_take_next_step",
+      "evidence"
+    ],
+    "properties": {
+      "conditions": {
+        "type": "array",
+        "description": "one entry per condition id, each exactly once",
+        "items": {
+          "type": "object",
+          "required": [
+            "id",
+            "pass",
+            "evidence",
+            "note"
+          ],
+          "properties": {
+            "id": {
+              "enum": [
+                "r1",
+                "r2",
+                "r3",
+                "r4",
+                "r5",
+                "r6"
+              ]
+            },
+            "pass": {
+              "type": "boolean"
+            },
+            "evidence": {
+              "type": "string",
+              "description": "a span copied verbatim from the draft"
+            },
+            "note": {
+              "type": "string",
+              "description": "why; required when pass is false"
+            }
+          }
+        }
+      },
+      "would_take_next_step": {
+        "type": "boolean",
+        "description": "whether this reader would take inputs.goal.next_if_worked now"
+      },
+      "evidence": {
+        "type": "string",
+        "description": "a span copied verbatim from the draft that decided would_take_next_step"
+      }
+    }
+  }
+}

package/examples/writing/essay/judge/lineup.packet.json

@@ -0,0 +1,64 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "lineup",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "blind lineup within this scope; a judge shown a generated passage beside the scope's three goldens cannot pick it out",
+  "instructions": "Each passage in inputs.candidates carries a capital-letter label. All but one were written by the writer of inputs.scope, for this form, audience and purpose, and approved by a person; exactly one comes from a new draft. Pick the label of the passage you believe comes from the new draft, judging by voice alone: rhythm, diction, sentence shape, what this writer would and would not say. Give your confidence from 0 (a guess) to 1 (certain), and in reason say what in the candidates decided it. Judge from the packet's inputs alone: do not open the spec, the draft or any other file the packet names. Answer only in the verdict shape given in verdict_schema.",
+  "inputs": {
+    "scope": {
+      "writer": "example-author",
+      "form": "essay",
+      "audience": "new managers",
+      "purpose": "teach"
+    },
+    "candidates": [
+      {
+        "label": "A",
+        "text": "So write the three questions on a card. Ask the first one. Then wait, longer than feels polite, because the first answer is the one they rehearsed and the second one is the one you came for."
+      },
+      {
+        "label": "B",
+        "text": "If you can read it in the tracker, do not ask for it in the room. Status already has a home, and your report is the one who put it there. Spend the half hour on what the tracker cannot hold: how the work looks from their side of it."
+      },
+      {
+        "label": "C",
+        "text": "Your first one-on-one with a new report is the only meeting on your calendar where they should set the agenda. Everything else you run. This one you hand over."
+      },
+      {
+        "label": "D",
+        "text": "The survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status. Read the tracker before you walk in, and leave status there."
+      }
+    ]
+  },
+  "verdict_schema": {
+    "type": "object",
+    "required": [
+      "pick",
+      "confidence",
+      "reason"
+    ],
+    "properties": {
+      "pick": {
+        "enum": [
+          "A",
+          "B",
+          "C",
+          "D"
+        ],
+        "description": "the label of the passage you believe comes from the new draft"
+      },
+      "confidence": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
+      "reason": {
+        "type": "string",
+        "description": "what in the candidates decided the pick"
+      }
+    }
+  }
+}

package/examples/writing/essay/judge/persona.packet.json

@@ -0,0 +1,73 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "persona",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "persona-consistency judge; the mentor stance holds, and no fact appears that is not in the claims ledger",
+  "instructions": "Read inputs.draft as the speaker inputs.persona describes. Report every break as an entry in breaks: the passage as evidence, copied verbatim from inputs.draft, at least three whole words; its kind; and why. The kind is one of: stance (the voice leaves inputs.persona.stance), assertion (it asserts something outside inputs.persona.may_assert), will_not_say (it says something inputs.persona.will_not_say rules out), unsourced_fact (it states a fact that none of inputs.claims holds). When inputs.claims is null, no claims ledger is declared and facts cannot be checked against sources: do not report unsourced_fact. If the voice holds throughout, breaks is an empty list. Answer only in the verdict shape given in verdict_schema.",
+  "inputs": {
+    "persona": {
+      "identity": "self",
+      "stance": "mentor",
+      "may_assert": [
+        "what the author did in their own first one-on-ones and what happened",
+        "the three questions the author uses now"
+      ],
+      "will_not_say": [
+        "a claim about what most managers do, beyond the survey's own figures",
+        "the name of anyone on the author's team"
+      ]
+    },
+    "claims": [
+      "29 of 41 people said their most useful one-on-one in the last quarter was one where they brought the first topic.",
+      "That is how an engineering manager I interviewed, eight years into the job, runs hers.",
+      "Her rule is short: the report owns the agenda.",
+      "My first one-on-one as a manager was a disaster, and the reason was simple: I ran it.",
+      "11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status.",
+      "What is taking more of your energy than it should?",
+      "What do you want to be doing more of in six months?",
+      "What should I stop doing, or start doing, that would make your week easier?",
+      "The most common free-text request in the survey, in 9 responses, was to be asked what they want to work on next."
+    ],
+    "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": [
+      "breaks"
+    ],
+    "properties": {
+      "breaks": {
+        "type": "array",
+        "description": "every place the persona breaks; empty when it holds",
+        "items": {
+          "type": "object",
+          "required": [
+            "evidence",
+            "kind",
+            "why"
+          ],
+          "properties": {
+            "evidence": {
+              "type": "string",
+              "description": "the passage, copied verbatim from the draft, at least three words"
+            },
+            "kind": {
+              "enum": [
+                "stance",
+                "assertion",
+                "will_not_say",
+                "unsourced_fact"
+              ]
+            },
+            "why": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}