@supersuit/hyperspec 0.1.0 → 0.3.0

package/bin/hyperspec.mjs

@@ -1,15 +1,57 @@
 #!/usr/bin/env node
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { loadSpec } from "../src/load.mjs";
 import { lintSpec } from "../src/rules.mjs";
 import { score, exitCode } from "../src/score.mjs";
 import { template } from "../src/template.mjs";
+import { writingTemplate } from "../src/writing-template.mjs";
+import { PROFILES, knownProfile } from "../src/profiles.mjs";
+import { readRecipe, checkRecipe } from "../src/recipe.mjs";
+import { approve } from "../src/writer.mjs";
+import { reproduce } from "../src/reproduce.mjs";
+import { regenerate } from "../src/regenerate.mjs";
+import { compare } from "../src/compare.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
   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,
+                               dna, persona, audience, goal, form, spine, sources) shown in full
+                               with placeholder values, dna/persona/audience/goal also carrying an
+                               open decision naming the question only the operator can answer;
+                               --fiction adds one character, same treatment; the skeleton never
+                               passes until its placeholders and open decisions are replaced with
+                               real content; exit 2 for a --profile with no value or one this
+                               linter does not know, --fiction or --form without --profile
+                               writing, --kind with it (use --form), or a folder that does not
+                               exist
+
+  recipe check <output-or-recipe> [--json]
+                               check a recipe's completeness (a path not ending .recipe.json
+                               means <path>.recipe.json)
+                               exit 0 ok (warns only), 1 no recipe found or a check failed,
+                               2 unreadable/invalid recipe JSON
+  recipe approve <recipe> --by <slug> [--json]
+                               set the recipe's approver, print remaining findings
+                               exit 0 once --by and the recipe are valid, 2 missing --by or
+                               unreadable recipe
+  reproduce <recipe> [--restore] [--store d] [--json]
+                               replay a recipe's hash checks against the blob store; never
+                               runs a model
+                               exit 0 reproduces cleanly, 1 a check failed, 2 unreadable recipe
+  regenerate <recipe> --out <path> --clicker <slug>
+             (--add-input n=p [--reads id]... | --swap-input n=p | --factory-version v)
+             [--run cmd] [--change text] [--store d] [--json]
+                               make a child recipe from a parent plus exactly one change
+                               exit 0 ok, 1 a stage failed or the child has failing verdicts,
+                               2 usage, 3 pending a runner
+  compare <child-recipe> --doctor cmd [--parent r] [--spec s] [--json]
+                               grade a child and its parent through one doctor against one spec
+                               exit 0 not regressed, 1 regressed, 2 usage or unreadable input
 
 Spec: SPEC.md`;
 
@@ -19,11 +61,39 @@ const cmd = argv[0];
 
 if (!cmd || cmd === "--help" || cmd === "-h") { console.log(HELP); process.exit(cmd ? 0 : 2); }
 
+// Each profile that wants its own init skeleton adds one entry here; a profile absent from this
+// map still lints (via PROFILES in profiles.mjs) but init falls back to the plain template for it.
+const PROFILE_TEMPLATES = { writing: writingTemplate };
+
 if (cmd === "init") {
   const file = argv[1];
   if (!file || file.startsWith("--")) { console.error("init needs a file path"); process.exit(2); }
   if (existsSync(file)) { console.error(`refusing to overwrite ${file}`); process.exit(2); }
-  writeFileSync(file, template({ title: flag("--title"), kind: flag("--kind") }));
+  const usage = (msg) => { console.error(msg); process.exit(2); };
+  const given = (name) => argv.includes(name);
+  // A value flag with nothing after it, or another flag after it, has no value.
+  const value = (name) => { const v = flag(name); return v === undefined || v.startsWith("--") ? undefined : v; };
+  const profileName = value("--profile");
+  if (given("--profile") && profileName === undefined) usage("--profile needs a value; known profiles: " + Object.keys(PROFILES).join(", "));
+  if (profileName !== undefined && !knownProfile(profileName)) {
+    usage(`unknown profile: ${profileName}; known profiles: ${Object.keys(PROFILES).join(", ") || "(none)"}`);
+  }
+  const writeTemplate = profileName !== undefined && Object.hasOwn(PROFILE_TEMPLATES, profileName) ? PROFILE_TEMPLATES[profileName] : undefined;
+  // The writing flags mean nothing to the plain template, and --kind means nothing to the writing
+  // one (its kind comes from --form); either would be silently dropped, so both are refused.
+  if (!writeTemplate) {
+    for (const f of ["--fiction", "--form"]) if (given(f)) usage(`${f} only applies with --profile writing`);
+  } else if (given("--kind")) {
+    usage("--kind does not apply with --profile writing; use --form, which sets kind and writing.form.name together");
+  }
+  if (given("--form") && value("--form") === undefined) usage("--form needs a value");
+  const folder = dirname(resolve(file));
+  if (!existsSync(folder) || !statSync(folder).isDirectory()) usage(`the folder ${dirname(file)} does not exist; create it first`);
+  const content = writeTemplate
+    ? writeTemplate({ title: flag("--title"), form: value("--form"), fiction: given("--fiction") })
+    : template({ title: flag("--title"), kind: flag("--kind") });
+  try { writeFileSync(file, content); }
+  catch (e) { usage(`could not write ${file}: ${e.code === "EACCES" ? "permission denied" : e.message}`); }
   console.log(`wrote ${file}; run: hyperspec lint ${file}`);
   process.exit(0);
 }
@@ -51,11 +121,261 @@ if (cmd === "lint") {
   else for (const r of reports) {
     if (r.error) { console.log(`${r.file}: ${r.error}`); continue; }
     console.log(`${r.file}: ${r.status} (${r.passed}/9)${r.open.length ? `, open: ${r.open.join(", ")}` : ""}`);
+    if (r.profile) console.log(`  ${r.profile.name}: ${r.profile.complete}/${r.profile.total} blocks complete`);
     for (const t of r.tests) if (!t.pass) console.log(`  ✗ ${t.n}. ${t.name}`);
     for (const f of r.findings) console.log(`    ${f.severity === "fail" ? "fail" : "warn"} [${f.test}] ${f.message}\n         fix: ${f.fix}`);
   }
   process.exit(worst);
 }
 
+// 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
+// for this verb is an error. This is the same discipline lint's own hand-rolled parser follows
+// above (a stray flag never swallows a file), generalized once repeated-flag verbs (regenerate's
+// --reads) and value flags (--out, --by, --doctor, ...) showed up.
+function parseArgs(args, { valueFlags = [], boolFlags = [], repeatableFlags = [] } = {}) {
+  const positionals = [];
+  const values = {};
+  for (const f of boolFlags) values[f] = false;
+  for (const f of repeatableFlags) values[f] = [];
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      if (repeatableFlags.includes(a)) {
+        const v = args[i + 1];
+        if (v === undefined || v.startsWith("--")) return { error: `${a} needs a value` };
+        values[a].push(v);
+        i += 2;
+        continue;
+      }
+      if (valueFlags.includes(a)) {
+        const v = args[i + 1];
+        if (v === undefined || v.startsWith("--")) return { error: `${a} needs a value` };
+        values[a] = v;
+        i += 2;
+        continue;
+      }
+      if (boolFlags.includes(a)) { values[a] = true; i += 1; continue; }
+      return { error: `unknown flag: ${a}` };
+    }
+    positionals.push(a);
+    i += 1;
+  }
+  return { positionals, values };
+}
+
+// name=path, split on the FIRST =, so a path that itself contains = survives intact. A value with
+// no = is a usage error (exit 2).
+function namePath(flagName, raw) {
+  const eq = raw.indexOf("=");
+  if (eq === -1) { console.error(`${flagName} needs name=path`); process.exit(2); }
+  return { name: raw.slice(0, eq), path: raw.slice(eq + 1) };
+}
+
+function printFindings(findings) {
+  if (!findings.length) { console.log("ok"); return; }
+  for (const f of findings) console.log(`${f.severity === "fail" ? "fail" : "warn"} [${f.field}] ${f.message}`);
+}
+
+function printPlan(plan) {
+  for (const p of plan ?? []) console.log(`  ${p.id}: ${p.action}${p.reason ? ` (${p.reason})` : ""}`);
+}
+
+if (cmd === "recipe") {
+  const sub = argv[1];
+
+  if (sub === "check") {
+    const parsed = parseArgs(argv.slice(2), { boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [target] = parsed.positionals;
+    const json = parsed.values["--json"];
+    if (!target) { console.error("recipe check needs a recipe or output path"); process.exit(2); }
+    const recipePath = target.endsWith(".recipe.json") ? target : `${target}.recipe.json`;
+
+    if (!existsSync(recipePath)) {
+      const msg = `no recipe beside ${target}`;
+      if (json) console.log(JSON.stringify({ recipe: recipePath, error: msg }, null, 2));
+      else console.error(msg);
+      process.exit(1);
+    }
+
+    const loaded = readRecipe(recipePath);
+    if (loaded.error) {
+      if (json) console.log(JSON.stringify({ recipe: recipePath, error: loaded.error }, null, 2));
+      else console.error(loaded.error);
+      process.exit(2);
+    }
+
+    const findings = checkRecipe(loaded.data);
+    const hasFail = findings.some((f) => f.severity === "fail");
+    if (json) console.log(JSON.stringify({ recipe: recipePath, findings }, null, 2));
+    else { console.log(`${recipePath}:`); printFindings(findings); }
+    process.exit(hasFail ? 1 : 0);
+  }
+
+  if (sub === "approve") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--by"], boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [recipePath] = parsed.positionals;
+    const json = parsed.values["--json"];
+    if (!recipePath) { console.error("recipe approve needs a recipe path"); process.exit(2); }
+    if (!parsed.values["--by"]) { console.error("recipe approve needs --by <slug>"); process.exit(2); }
+
+    let findings;
+    try {
+      findings = approve(recipePath, parsed.values["--by"]);
+    } catch (e) {
+      if (json) console.log(JSON.stringify({ recipe: recipePath, error: e.message }, null, 2));
+      else console.error(e.message);
+      process.exit(2);
+    }
+
+    if (json) console.log(JSON.stringify({ recipe: recipePath, approver: parsed.values["--by"], findings }, null, 2));
+    else { console.log(`${recipePath}: approver set to ${parsed.values["--by"]}`); printFindings(findings); }
+    process.exit(0);
+  }
+
+  console.error(`unknown recipe subcommand: ${sub}\n\n${HELP}`);
+  process.exit(2);
+}
+
+if (cmd === "reproduce") {
+  const parsed = parseArgs(argv.slice(1), { valueFlags: ["--store"], boolFlags: ["--restore", "--json"] });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [recipePath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  if (!recipePath) { console.error("reproduce needs a recipe path"); process.exit(2); }
+
+  const result = reproduce(recipePath, { store: parsed.values["--store"], restore: parsed.values["--restore"] });
+  if (json) console.log(JSON.stringify(result, null, 2));
+
+  if (result.error) {
+    if (!json) console.error(result.error);
+    process.exit(2);
+  }
+  if (!result.ok) {
+    if (!json) {
+      console.error(`first mismatch: ${result.firstMismatch}`);
+      for (const step of result.steps) console.log(`  ${step.ok ? "ok  " : "FAIL"} ${step.ref}${step.why ? `: ${step.why}` : ""}`);
+      if (result.restored) console.log("restored the output file from its blob");
+    }
+    process.exit(1);
+  }
+  if (!json) {
+    for (const step of result.steps) console.log(`  ok   ${step.ref}`);
+    if (result.restored) console.log("restored the output file from its blob");
+    console.log("reproduces cleanly");
+  }
+  process.exit(0);
+}
+
+if (cmd === "regenerate") {
+  const parsed = parseArgs(argv.slice(1), {
+    valueFlags: ["--out", "--clicker", "--add-input", "--swap-input", "--factory-version", "--run", "--change", "--store"],
+    boolFlags: ["--json"],
+    repeatableFlags: ["--reads"],
+  });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [recipePath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  if (!recipePath) { console.error("regenerate needs a parent recipe path"); process.exit(2); }
+  if (parsed.values["--reads"].length && parsed.values["--add-input"] === undefined) {
+    console.error("--reads is only valid with --add-input");
+    process.exit(2);
+  }
+
+  const change = {};
+  if (parsed.values["--add-input"] !== undefined) {
+    const pair = namePath("--add-input", parsed.values["--add-input"]);
+    change.addInput = { ...pair, reads: parsed.values["--reads"] };
+  }
+  if (parsed.values["--swap-input"] !== undefined) {
+    change.swapInput = namePath("--swap-input", parsed.values["--swap-input"]);
+  }
+  if (parsed.values["--factory-version"] !== undefined) change.factoryVersion = parsed.values["--factory-version"];
+
+  const result = regenerate(recipePath, {
+    out: parsed.values["--out"],
+    clicker: parsed.values["--clicker"],
+    change,
+    run: parsed.values["--run"],
+    changeText: parsed.values["--change"],
+    store: parsed.values["--store"],
+  });
+  if (json) console.log(JSON.stringify(result, null, 2));
+
+  if (result.usage) {
+    if (!json) console.error(result.error);
+    process.exit(2);
+  }
+  if (!result.ok) {
+    if (!json) {
+      console.error(result.failedStage ? `stage ${result.failedStage} failed: ${result.error}` : result.error);
+      if (result.plan?.length) printPlan(result.plan);
+    }
+    process.exit(1);
+  }
+  if (result.pending) {
+    if (!json) {
+      const waiting = result.plan.filter((p) => p.action === "rerun").map((p) => p.id);
+      console.log(`pending; stages waiting for a runner: ${waiting.join(", ") || "(none)"}`);
+      printPlan(result.plan);
+      console.log(`child recipe: ${result.childRecipe}`);
+      console.log("a pending child cannot be finished in place yet; to produce the output, rerun regenerate on the parent with --run <command> and a new --out");
+    }
+    process.exit(3);
+  }
+  if (result.failedVerdicts?.length) {
+    if (!json) {
+      console.log(`child written despite failing verdict(s): ${result.failedVerdicts.join(", ")}`);
+      printPlan(result.plan);
+      console.log(`child recipe: ${result.childRecipe}`);
+      console.log(`output: ${result.output}`);
+    }
+    process.exit(1);
+  }
+  if (!json) {
+    printPlan(result.plan);
+    console.log(`child recipe: ${result.childRecipe}`);
+    console.log(`output: ${result.output}`);
+  }
+  process.exit(0);
+}
+
+if (cmd === "compare") {
+  const parsed = parseArgs(argv.slice(1), { valueFlags: ["--doctor", "--parent", "--spec"], boolFlags: ["--json"] });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [childRecipePath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  if (!childRecipePath) { console.error("compare needs a child recipe path"); process.exit(2); }
+
+  const result = compare(childRecipePath, {
+    doctor: parsed.values["--doctor"],
+    parent: parsed.values["--parent"],
+    spec: parsed.values["--spec"],
+  });
+  if (json) console.log(JSON.stringify(result, null, 2));
+
+  // Both a usage error and a check-failed error (missing output, escaping path, ...) map to
+  // 2 here — compare's own ok:false without a usage flag is still "could not grade", i.e. an
+  // unreadable-input class failure, not a graded-but-worse-1 class one.
+  if (!result.ok) {
+    if (!json) console.error(result.error);
+    process.exit(2);
+  }
+  if (!json) {
+    for (const w of result.warnings) console.log(`warn: ${w}`);
+    if (result.ledger) console.log(`ledger: ${result.ledger}`);
+  }
+  if (result.regressed) {
+    if (!json) console.log(`regression: child scored ${result.child.score} vs parent ${result.parent.score}; suspect: ${result.suspect ?? "unknown"}`);
+    process.exit(1);
+  }
+  if (!json) console.log(`child scored ${result.child.score} vs parent ${result.parent.score} (delta ${result.delta})`);
+  process.exit(0);
+}
+
 console.error(`unknown command: ${cmd}\n\n${HELP}`);
 process.exit(2);

package/examples/minimal.hyperspec.md

@@ -7,7 +7,7 @@ decisions:
     state: decided
     value: the operator, reading on a phone
     source: interview A2
-    author: gary-sheng
+    author: example-author
     chosen_by: human
   - id: length
     state: delegated
@@ -22,7 +22,7 @@ requirements:
     check:
       rubric: ask the simulated reader to define the term; pass only on a correct definition
     source: design doc, audience block
-    author: gary-sheng
+    author: example-author
 rejects:
   - hype words about AI
 examples:

package/examples/recipe/doctor.mjs

@@ -0,0 +1,11 @@
+// The doctor `hyperspec compare --doctor "node doctor.mjs"` runs once on the parent's output and
+// once on the child's, with the same spec. stdin: { output, spec }, both absolute paths. The last
+// stdout line is { "score": <number>, "notes": "..." }. This one scores an essay by how many
+// claims it carries.
+import { readFileSync } from "node:fs";
+
+const { output } = JSON.parse(readFileSync(0, "utf8"));
+const essay = readFileSync(output, "utf8");
+const section = essay.split("## Claims")[1]?.split("## ")[0] ?? "";
+const score = section.split("\n").filter((line) => line.startsWith("- ")).length;
+console.log(JSON.stringify({ score, notes: `${score} claims` }));

package/examples/recipe/essay.hyperspec.md

@@ -0,0 +1,50 @@
+---
+hyperspec: "0.1"
+title: What a recipe is for
+kind: essay
+decisions:
+  - id: audience
+    state: decided
+    value: someone who has never rerun a piece of work from its inputs
+    source: materials/notes.md
+    author: example-author
+    chosen_by: human
+  - id: shape
+    state: decided
+    value: the claims from the calls first, then the terms they lean on
+    source: stages.mjs
+    author: example-author
+    chosen_by: human
+requirements:
+  - id: every-claim-spoken
+    text: every claim is a line someone said on a call
+    fails_when: the essay carries a claim that no call transcript contains
+    check:
+      station: stages.mjs claims() copies lines from the calls and never writes one
+    source: materials/call.md
+    author: example-author
+  - id: more-claims-score-higher
+    text: an essay built from more calls carries more claims
+    fails_when: compare scores an essay with an added call no higher than its parent
+    check:
+      rubric: doctor.mjs counts the bullets under the Claims heading
+    source: doctor.mjs
+    author: example-author
+rejects:
+  - a claim nobody said on a call
+examples:
+  - path: materials/call.md
+    why: the raw call every claim is copied from, word for word
+resume:
+  next_action: add the next call with hyperspec regenerate --add-input, then compare the two essays
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: runs.jsonl
+---
+
+# What a recipe is for
+
+The example spec for `examples/recipe/`. The factory builds a short essay from call transcripts
+and a set of notes, and writes a recipe beside it.

package/examples/recipe/factory.mjs

@@ -0,0 +1,29 @@
+// The example factory: two inputs, three stages, and a recipe written beside the output.
+// Run it with `node factory.mjs`. It writes essay.md and essay.md.recipe.json next to itself.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { startRecipe } from "@supersuit/hyperspec/recipe";
+import { claims, draft, terms, verdict } from "./stages.mjs";
+
+const here = (p) => fileURLToPath(new URL(p, import.meta.url));
+const read = (p) => readFileSync(here(p), "utf8");
+
+const recipe = startRecipe({
+  output: here("essay.md"),
+  factory: { name: "example-essay", version: "1.0.0" },
+  spec: here("essay.hyperspec.md"),
+  clicker: "you",
+});
+recipe.input("call", here("materials/call.md"));
+recipe.input("notes", here("materials/notes.md"));
+
+const c = claims([read("materials/call.md")]);
+recipe.stage({ id: "claims", reads: ["input:call"], output: c, verdict: verdict("claims", c) });
+const t = terms([read("materials/notes.md")]);
+recipe.stage({ id: "terms", reads: ["input:notes"], output: t, verdict: verdict("terms", t) });
+const d = draft(c, t);
+recipe.stage({ id: "draft", reads: ["stage:claims", "stage:terms"], output: d, verdict: verdict("draft", d) });
+
+const { findings } = recipe.finish();
+console.log("wrote essay.md and essay.md.recipe.json");
+for (const f of findings) console.log(`${f.severity} [${f.field}] ${f.message}`);

package/examples/recipe/materials/call-2.md

@@ -0,0 +1,2 @@
+Ana: A recipe you cannot rerun is a receipt.
+Sam: So the second call goes in as one more input, and only the claims change.

package/examples/recipe/materials/call.md

@@ -0,0 +1,3 @@
+Maya: The recipe is the part people skip.
+Sam: Because writing it down feels like overhead.
+Maya: It stops being overhead the day you have to redo the work.

package/examples/recipe/materials/notes.md

@@ -0,0 +1,3 @@
+stage: one step of a factory, keyed by everything it read
+blob: the exact bytes of an input, stored by their hash
+recipe: the record of what made an output, from what, and who approved it

package/examples/recipe/runner.mjs

@@ -0,0 +1,20 @@
+// The runner `hyperspec regenerate --run "node runner.mjs"` calls once per stage it must rerun.
+// stdin: { stage, reads: [{ ref, sha256, path }], model }. Each read is a temp file holding the
+// exact bytes that ref resolved to. stdout: the stage's output, byte for byte. The last stderr
+// line starting "VERDICT " is the stage's verdict. A runner that prints none fails the stage:
+// silence is not a verdict.
+import { readFileSync } from "node:fs";
+import { claims, draft, terms, verdict } from "./stages.mjs";
+
+const job = JSON.parse(readFileSync(0, "utf8"));
+const text = (ref) => readFileSync(job.reads.find((r) => r.ref === ref).path, "utf8");
+const inputs = () => job.reads.filter((r) => r.ref.startsWith("input:")).map((r) => readFileSync(r.path, "utf8"));
+
+let output;
+if (job.stage === "claims") output = claims(inputs());
+else if (job.stage === "terms") output = terms(inputs());
+else if (job.stage === "draft") output = draft(text("stage:claims"), text("stage:terms"));
+else { console.error(`runner.mjs does not know stage ${job.stage}`); process.exit(2); }
+
+process.stdout.write(output);
+console.error(`VERDICT ${JSON.stringify(verdict(job.stage, output))}`);

package/examples/recipe/stages.mjs

@@ -0,0 +1,31 @@
+// The three stages of the example factory. Each is a plain text transform with no model in it,
+// so the same inputs always give the same bytes. factory.mjs runs them the first time;
+// runner.mjs runs them again when `hyperspec regenerate --run` asks for a stage.
+
+// claims: every line spoken on a call, without the speaker's name, as a bullet.
+export function claims(calls) {
+  const lines = calls.flatMap((text) => text.split("\n"))
+    .map((line) => line.replace(/^[^:]+:\s*/, "").trim())
+    .filter(Boolean);
+  return lines.map((line) => `- ${line}`).join("\n") + "\n";
+}
+
+// terms: every "term: definition" line in the notes, sorted by term.
+export function terms(notes) {
+  const lines = notes.flatMap((text) => text.split("\n")).filter((line) => line.includes(":"));
+  return lines
+    .map((line) => { const i = line.indexOf(":"); return [line.slice(0, i).trim(), line.slice(i + 1).trim()]; })
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([term, meaning]) => `- **${term}**: ${meaning}`)
+    .join("\n") + "\n";
+}
+
+// draft: the essay, built from the two earlier stages.
+export function draft(claimsText, termsText) {
+  return `# What a recipe is for\n\n## Claims\n\n${claimsText}\n## Terms\n\n${termsText}`;
+}
+
+// The verdict each stage reports: a stage that produced nothing fails.
+export function verdict(stage, output) {
+  return { station: `${stage}-not-empty`, pass: output.trim().length > 0, note: "" };
+}

package/examples/writing/essay/goldens/close.md

@@ -0,0 +1,2 @@
+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/goldens/opening.md

@@ -0,0 +1,2 @@
+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.

package/examples/writing/essay/materials/interview-notes.md

@@ -0,0 +1,12 @@
+Interview notes, a thirty-minute call with an engineering manager of eight years, taken by the
+author during the call. Considered: the manager reviewed these notes afterwards and corrected two
+lines.
+
+- Her rule: the report owns the agenda. She keeps a shared document per person; they add items
+  before the meeting, and she adds hers last, at the bottom.
+- "If I have something urgent, it is not a one-on-one topic. I send it the day it happens."
+- The first one-on-one with a new report is always the same: she asks how they like to receive
+  feedback, in writing or out loud, right away or at the end of the week.
+- Her warning: new managers treat silence as a problem. "Wait. Count to five. The real answer is
+  the second one."
+- She cancels a one-on-one only when the report asks her to, never on her own.

package/examples/writing/essay/materials/team-survey.md

@@ -0,0 +1,7 @@
+Summary of an internal survey the author's team ran in the spring, 41 responses, figures checked
+against the raw export by a second person. Verified.
+
+- 29 of 41 said their most useful one-on-one in the last quarter was one where they brought the
+  first topic.
+- 11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status.
+- The most common free-text request, in 9 responses: "ask me what I want to work on next."

package/examples/writing/essay/materials/voice-memo.md

@@ -0,0 +1,18 @@
+Voice memo transcript, recorded by the author on a walk, lightly cleaned. Raw thinking.
+
+My first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a
+list. I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes
+later my report said "cool, thanks" and left, and I had learned nothing I could not have read in
+the tracker.
+
+What I wish someone had told me: the first one-on-one is the only meeting where they get to set
+the agenda. If you set it, you have told them what the meeting is for, and it is for you.
+
+The three questions I use now. 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? Then I shut up.
+
+Status goes in the tracker. If a one-on-one is a status meeting, cancel it and read the tracker.
+
+Aside, probably not for this piece: my second manager used to walk the one-on-ones outside. I
+liked it but I do not think it is the point.