@supersuit/hyperspec 0.5.0 → 0.6.0

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

@@ -3,8 +3,8 @@
 {"id":"s2","start":119,"end":199,"label":"aside","text":"Considered: the manager reviewed these notes afterwards and corrected two\nlines."}
 {"id":"s3","start":201,"end":240,"label":"claim","source":"interview with an engineering manager of eight years","text":"- Her rule: the report owns the agenda."}
 {"id":"s4","start":241,"end":356,"label":"claim","source":"interview with an engineering manager of eight years","text":"She keeps a shared document per person; they add items\n  before the meeting, and she adds hers last, at the bottom."}
-{"id":"s5","start":357,"end":448,"label":"quote","speaker":"the engineering manager interviewed","text":"- \"If I have something urgent, it is not a one-on-one topic. I send it the day it happens.\""}
+{"id":"s5","start":357,"end":448,"label":"quote","speaker":"dana, an engineering manager","text":"- \"If I have something urgent, it is not a one-on-one topic. I send it the day it happens.\""}
 {"id":"s6","start":449,"end":617,"label":"claim","source":"interview with an engineering manager of eight years","text":"- The first one-on-one with a new report is always the same: she asks how they like to receive\n  feedback, in writing or out loud, right away or at the end of the week."}
 {"id":"s7","start":618,"end":673,"label":"claim","source":"interview with an engineering manager of eight years","text":"- Her warning: new managers treat silence as a problem."}
-{"id":"s8","start":674,"end":733,"label":"quote","speaker":"the engineering manager interviewed","text":"\"Wait. Count to five. The real answer is\n  the second one.\""}
+{"id":"s8","start":674,"end":733,"label":"quote","speaker":"dana, an engineering manager","text":"\"Wait. Count to five. The real answer is\n  the second one.\""}
 {"id":"s9","start":734,"end":812,"label":"claim","source":"interview with an engineering manager of eight years","text":"- She cancels a one-on-one only when the report asks her to, never on her own."}

package/examples/writing/essay.hyperspec.md

@@ -74,7 +74,7 @@ examples:
   - path: dna/essay-new-managers-teach/goldens/opening.md
     why: the claim lands in the first sentence, and the two short sentences after it turn it into an instruction
 resume:
-  next_action: outline the four spine claims against the form's required parts, citing the segments each claim points at
+  next_action: hand essay/draft.md to the doctor for the rubric checks in r1, r4 and r5, now that hyperspec check passes it
 feedback:
   issues: https://github.com/SupersuitUp/hyperspec/issues
   fork: MIT; fork it for your own purposes
@@ -148,6 +148,9 @@ writing:
       - one-on-one
       - report
       - tracker
+    terms:
+      - running agenda
+      - status meeting
     believes_now: a one-on-one is where a manager catches up on how the work is going
     wants: a plan for the first meeting that will not waste either person's half hour
     reads_on: a phone, in the ten minutes before the meeting
@@ -176,11 +179,11 @@ writing:
       max: 1100
       unit: words
     required_parts:
-      - an opening that states the claim
-      - the story of the author's first one-on-one
+      - who sets the agenda
+      - my first one-on-one
       - the three questions
       - what to do with the answers
-      - a close the reader can act on
+      - before the meeting
     stations:
       - the three questions render as a numbered list
     check:
@@ -219,8 +222,16 @@ fiction: false
 # Hand your first one-on-one to the person you manage
 
 A worked example of the writing profile: an essay for new managers, specified before a word of
-it is drafted. Every file this spec names ships beside it. `essay/claims.jsonl` does not exist
-yet, because the claims ledger is written during drafting.
+it is drafted. Every file this spec names ships beside it. The draft is `essay/draft.md`, and
+the claims ledger written while drafting it is `essay/claims.jsonl`. The draft passes every
+deterministic station:
+
+```bash
+npx @supersuit/hyperspec check essay.hyperspec.md --draft essay/draft.md
+```
+
+The required parts are the draft's section headings, because the form station finds a required
+part by its heading.
 
 The writer's voice for this piece comes from a scope folder, `dna/essay-new-managers-teach/`:
 the goldens this writer approved for essays that teach new managers, and the features measured

package/examples/writing/story/claims.jsonl

@@ -0,0 +1,9 @@
+{"text":"Flour is weighed at Ines's, never scooped.","source":"bakery-visit#s10","span":"Flour is weighed, never scooped."}
+{"text":"The water temperature is checked every batch at Ines's","source":"bakery-visit#s11","span":"Water temperature is checked every batch."}
+{"text":"Ines does not talk while she shapes.","source":"bakery-visit#s8","span":"The owner does not talk while shaping."}
+{"text":"Talking happens at the mixer and at the till","source":"bakery-visit#s9","span":"Talking happens at the mixer and at the till."}
+{"text":"In winter the rye proofs about three hours at room temperature.","source":"bakery-visit#s4","span":"Rye sourdough proofs about three hours at room temperature in winter."}
+{"text":"The back left of the deck oven runs hot, so every tray is turned halfway through the bake.","source":"bakery-visit#s5","span":"Trays are turned halfway through the bake because the back left of a deck oven runs hot."}
+{"text":"The doors open to customers at 7:00.","source":"bakery-visit#s6","span":"The doors open to customers at 7:00."}
+{"text":"The first person in is usually a regular.","source":"bakery-visit#s7","span":"The first person in is usually a regular."}
+{"text":"turning those trays with her since I was sixteen","source":"notes#s2","span":"the apprentice she took on at sixteen, now nineteen"}

package/examples/writing/story/draft.md

@@ -0,0 +1,267 @@
+# The Rye
+
+## 3:40
+
+The alarm at the bakery went at 3:20, but Ines was always there first, so in three years I never
+once heard it. What I heard, coming in the back door at twenty to four with my hands in my
+pockets, was the mixer. It had a knock in it, a slow one, like it was trying to remember
+something.
+
+She was standing over the bowl with her sleeves pushed past the elbow and her glasses on top of
+her head, where they stayed until the till opened. She did not look round. She never did. The
+back door sticks in winter and you have to put your shoulder to it, so she always knew it was me
+before she could have seen me.
+
+"You're late," she said.
+
+I wasn't. She knew I wasn't. The clock over the proving cabinet said 3:41, and it runs a minute
+fast, and she was the one who set it that way.
+
+"The bus," I said anyway, because that is how we started.
+
+"Flour first. Then you can talk."
+
+So I did the flour. Flour is weighed at Ines's, never scooped. There is a scoop in the bin, a
+steel one with a dent in the lip, and in three years I have only ever seen it used to push the
+flour level before the lid goes back on. I set the bowl on the scale and zeroed it and poured
+until the number stopped where she wanted it, and then I took out a handful and put back half
+of that, because the last few grams go in by hand, and she was watching the scale even though
+she was not watching me.
+
+Behind us the deck oven was coming up to heat. The deck oven is three stone shelves stacked one
+over another inside a steel wall, each with its own door, and it takes the better part of an
+hour to get hot enough. Somewhere in that hour it starts to make the noise. It is not loud. It
+is a kind of tick, then a longer sound like somebody dragging a chair in the flat upstairs, then
+nothing for a while, then the tick again.
+
+It made the noise while I was weighing the second batch. I looked at the oven and then at Ines,
+and she did not look at either of us.
+
+"Okay but like," I said, "if the oven's made that noise since March, is it a noise, or is that just
+how the oven talks now?"
+
+"Water," she said.
+
+She put the thermometer in the water herself, the way she did for every batch, and read it and
+said nothing, which meant it was right. The water temperature is checked every batch at Ines's,
+even when the water comes out of the same tap at the same time on the same morning as the day
+before. I have never asked her why. I check it too.
+
+We worked. There is a radio on the shelf above the sink and nobody has turned it on since I have
+worked there. The mixer knocked. The oven ticked and dragged its chair. Outside it was still
+completely dark, and the street lamp at the corner made the frost on the window look like a
+thumbprint.
+
+The letter from the school was in the inside pocket of my coat, which was on the hook by the back
+door. I had moved it there from my bag on the bus, and then back to my bag, and then back to the
+coat, because the coat was closer. It was two pages. The first page said I had a place, and the
+second page said when term started, which was the autumn, in a city four hours away by train. I
+had read both pages enough times that the fold had gone soft.
+
+I did not look at the coat. I looked at the dough.
+
+On the calendar by the till, which I could see from the bench if I leaned, somebody had drawn a
+ring round Friday in red pen. Ines does not use red pen. She uses a pencil she keeps behind her
+ear and sharpens with a knife. I leaned, and looked, and leaned back.
+
+The starter was on the shelf above the mixer, where it always was. The starter is a wide glass
+jar with a cloth over the top held on by a rubber band, and everything we make that is sour
+comes out of it. It is the only thing in the bakery she has never let me touch. I have fed the
+mixer and cleaned the oven floor and scraped the bins and carried the flour sacks up from the
+cellar two at a time, and I have never once taken the cloth off that jar.
+
+"Is the rye going in the big bowl?" I asked, although it always went in the big bowl.
+
+"Big bowl," she said.
+
+## 4:30
+
+Ines does not talk while she shapes. Talking happens at the mixer and at the till, and the bench
+is for your hands. I learned that in my first week and I have never had to be told it twice. The
+silence at the bench is the kind that makes you hear how loud your own questions are.
+
+So at half past four we stood at the bench with the dough between us and did not talk.
+
+She cut the white dough into pieces with the bench knife, and weighed each piece, and pushed each
+one across to me, and I rounded them and set them seam up on the floured cloth in rows. Her
+knife was faster than my hands. It always was. She would cut the last piece and wipe the blade
+and wait, and I would still have six to go, and she would not help, and she would not watch me
+either. She would look at the window, where there was nothing yet to look at.
+
+When the white was done she went to the big bowl and turned the rye out onto the bench. Rye does
+not behave like the white. It is heavy and it is wet and it sticks to everything, and it does not
+stretch so much as slump, and you have to shape it quickly with wet hands before it decides to
+be the shape of the bench instead of the shape of the basket.
+
+She cut it into four and weighed the four. Then she wiped the knife and put it down on my side of
+the bench, and she went to the sink, and she wet her hands, and she dried them.
+
+I stood there. The rye sat there. The oven ticked.
+
+"I can do the rye," I said, and then I remembered where we were and said the rest quietly. "I
+mean, I think I can do the rye. I did it Tuesday, kind of."
+
+On Tuesday I had held the basket while she shaped. That was what I meant by kind of.
+
+She did not answer. That was allowed, at the bench. She took the cloth off the white rounds and
+checked them with one finger, and put the cloth back, and then she went through to the front and
+started taking the chairs down off the tables, which was the job she always gave me.
+
+So I did the rye.
+
+I wet my hands the way she did, up to the wrist. I took the first piece and folded it in on itself
+and turned it and folded it, and it stuck to my palm and I wet my hand again and it stuck again,
+and I could hear the chairs going down in the front, one leg and then the other three, and I did
+not look up. The second piece was better. The third piece tore and I had to fold the torn side
+under and hope. The fourth piece was the best one I have ever done, and there was nobody at the
+bench to see it, which I think was the point, or I think now was the point, and I did not think
+either of those things at the time. At the time I only thought about my hands.
+
+I put the four of them seam up in the baskets and dusted them and covered them. The baskets are
+old, and the rye has worn a pattern into the cane that is there even when they are empty.
+
+The proof is the long wait after shaping, when the dough sits and rises before it goes in the
+oven, and with rye you cannot hurry it. In winter the rye proofs about three hours at room
+temperature. Ines will not put it in the proving cabinet. She says the cabinet is for the white.
+So the four baskets went on the shelf by the window, and would sit there until well after the
+doors opened, and nothing either of us did in the meantime would make them go any faster.
+
+She came back from the front with flour on the knees of her trousers from the chairs. She looked
+at the four baskets on the shelf for about as long as it takes to read a price, and then she
+looked at the bench, which I had scraped clean, and then she went to the mixer.
+
+"Scrape the bowl," she said.
+
+I scraped the bowl.
+
+## 5:50
+
+By ten to six the oven was full and the kitchen smelled the way it smells only for about an hour
+a day, which is the hour I would pick if somebody made me pick one.
+
+The back left of the deck oven runs hot, so every tray is turned halfway through the bake. Ines
+has a timer on a string round her neck for it. She does not trust the ones on the oven. When it
+goes she opens each door in turn and pulls each tray out with the peel, and spins it, and pushes
+it back, so that the side that was at the back is at the front, and nothing comes out darker on
+one end than the other.
+
+"Left side runs hot," she said, as the first tray went in, as if I had not been turning those
+trays with her since I was sixteen. "Turn them at eight minutes."
+
+I set my own timer, which I did not need to do, because hers would go at the same time.
+
+We stood in front of the oven. There is nothing to do in that eight minutes except stand in front
+of the oven and not open it. The noise came and went. The street outside was starting to go from
+black to the color of dishwater. A van went past without stopping.
+
+The timer went. She opened the top door, and the heat came out, and she slid the peel under the
+first tray and drew it out onto the lip of the door and started to turn it.
+
+"It's sold," she said.
+
+She said it to the tray. She turned the tray, and pushed it back in, and pulled out the second.
+
+I did not say anything, because I did not know yet that she had said anything. It went past me
+the way the van had gone past. Then it came back.
+
+"What's sold?" I said. I knew what was sold.
+
+"The bakery. Friday." She turned the second tray and pushed it back and shut the top door and
+opened the middle one.
+
+"Sold like," I said, "sold? Like someone else is going to be here? Like I come in on Monday and
+somebody else is at the mixer, is that what, is that the sold you mean?"
+
+"Not a bakery," she said. "They want the room. Not the ovens."
+
+She pulled out the third tray and turned it. She had not burnt herself on a tray in all the time
+I had known her, and she did not burn herself then. Her hands did exactly what they always did.
+I watched them because I did not know what else to watch.
+
+"Then what happens to the ovens?" I said. "Then what happens to the mixer. Is somebody going to buy
+the mixer? It knocks. Does the person who buys it know it knocks?"
+
+She shut the middle door and opened the bottom one.
+
+"Is that why there's a ring round Friday?" I said. "Is that what the red pen is?"
+
+"Sold means sold," she said. "Get the next tray."
+
+I got the next tray. It was the seeded rolls, which I had shaped at five, and I put them on the
+peel and she put them in, and I stood with the empty peel in my hands while she shut the door and
+the heat stopped coming out.
+
+I wanted to ask how long she had known. I wanted to ask whether the new people had been in, and
+when, and whether they had stood in this kitchen while I was at home asleep, and whether they had
+looked at the baskets on the shelf and thought they were just baskets. I did not ask any of it.
+I stood there with the peel and I thought about the letter in my coat, and I thought, she has
+known this for days, maybe weeks, and every one of those mornings she came in before me and set
+the clock a minute fast and told me I was late.
+
+That was the only time all morning I nearly told her. The words got as far as the back of my
+teeth.
+
+The timer on the string went. She turned the next tray.
+
+"Rolls come out at sixteen," she said. "Get the racks."
+
+I got the racks.
+
+## 6:55
+
+At five to seven the front was ready. The chairs were down, the counter was wiped, the white was
+in the baskets behind the till and the rolls were on the racks, and the four rye loaves were still
+on the shelf by the window under their cloths, still rising, a long way from done.
+
+The doors open to customers at 7:00. The first person in is usually a regular. Through the glass
+I could see Walter already standing on the step with his collar up and his dog sitting on his
+foot, which was what the dog did in winter. Ines keeps a biscuit in her apron for the dog and has
+never once said so.
+
+She was counting the float into the till. I stood behind the counter with my hands flat on it.
+The letter was still in my coat. The coat was still on the hook by the back door, which was as
+far from the counter as you can get in the bakery and still be inside it.
+
+"I got into a school," I said.
+
+She went on counting. She got to the end of the coins and closed the drawer.
+
+"A baking school," I said. "In the city. It's a proper one, it's the one with the, they do the whole
+year on bread, and then pastry, and I applied in the spring and I didn't think, I mean I didn't
+think I'd get in, and then I did. It starts in the autumn. I was going to tell you. I was going to
+tell you the day the letter came, and then I got here and you were at the mixer and it felt like,
+I don't know. It felt like the wrong time to say anything to anybody."
+
+She looked at the four baskets on the shelf by the window.
+
+Then she walked past me into the back, and I heard her feet on the flour-dusty floor, and I heard
+her stop by the mixer, and I stood there with my hands on the counter and looked at Walter's dog.
+
+When she came back she had the starter.
+
+She had the jar in both hands, the way you carry something you have filled too full. The cloth
+was still on, and the rubber band, and the glass had a rim of dried flour at the top where it had
+risen in the night and fallen back. She put it on the counter between us and took her hands away.
+
+"Feed it at noon," she said. "Equal weight flour and water. Weigh it."
+
+I looked at the jar. I did not pick it up. I have scraped the bins and carried the sacks and
+cleaned the oven floor, and I had never once taken the cloth off that jar, and now it was on the
+counter in front of me with nobody's hands on it.
+
+"Every day," she said. "Not most days. Keep it out of the sun."
+
+"Okay," I said. "Okay. So is that a yes, or is that the face you make when it's a yes?"
+
+She took the glasses off the top of her head and put them on, which she only does for the till.
+
+"Doors," she said.
+
+I picked up the jar. It was heavier than it looked, and it was warm on the side that had faced
+the oven. I held it against my chest with one arm while she walked to the front and turned the
+sign and let Walter in, and Walter said good morning to her by name, and she said good morning to
+him by his, and she bent down to the dog with her hand already in her apron.
+
+Behind me, on the shelf by the window, under their cloths, the four rye loaves I had shaped were
+still rising, and the dough had lifted the cloth off the edge of the first basket by the width of
+a finger.

package/examples/writing/story.hyperspec.md

@@ -74,7 +74,7 @@ examples:
   - path: story/goldens/dialogue.md
     why: three short lines carry a ritual both characters know, without either of them naming it
 resume:
-  next_action: draft scene-1 from the scene list with Theo's knowledge as of scene-1
+  next_action: hand story/draft.md to the doctor for the rubric checks in r1 and r5, now that hyperspec check passes it
 feedback:
   issues: https://github.com/SupersuitUp/hyperspec/issues
   fork: MIT; fork it for your own purposes
@@ -145,6 +145,10 @@ writing:
       - bakery
       - apprentice
       - sourdough
+    terms:
+      - proof
+      - starter
+      - deck oven
     believes_now: nothing yet about this author or these two people
     wants: a story they can finish in one sitting and keep thinking about
     reads_on: print, in one sitting of about fifteen minutes
@@ -173,8 +177,10 @@ writing:
       max: 4000
       unit: words
     required_parts:
-      - four scenes, in the scene list's order
-      - a last line about bread
+      - "3:40"
+      - "4:30"
+      - "5:50"
+      - "6:55"
     stations:
       - continuity against the scene list
       - knowledge-leak check, per character, per scene
@@ -284,5 +290,14 @@ fiction: true
 
 A worked example of the writing profile for fiction: a short story with two characters, each
 specified well enough that an agent can write their dialogue and a judge can tell them apart.
-Every file this spec names ships beside it. `story/claims.jsonl` does not exist yet, because the
-claims ledger is written during drafting.
+Every file this spec names ships beside it. The draft is `story/draft.md`, and the claims ledger
+written while drafting it is `story/claims.jsonl`: every process detail in the draft, pointed at
+the bakery visit notes. The draft passes every deterministic station:
+
+```bash
+npx @supersuit/hyperspec check story.hyperspec.md --draft story/draft.md
+```
+
+The four required parts are the scene headings, one per scene of the scene list, in its order.
+The story is fiction, so the quotes station skips it: its dialogue is invented, not quoted from
+a material, and is checked against each character's lines by a later release's character stations.

package/package.json

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

package/src/check.mjs

@@ -0,0 +1,245 @@
+// `hyperspec check`: run every deterministic station against a draft, once the spec that
+// declares them is itself lint-clean. This module is the command's logic, independent of the
+// CLI's argv parsing and printing (bin/hyperspec.mjs owns those), the same split rules.mjs and
+// score.mjs already keep for `lint`.
+//
+// A draft is never checked against a spec that is not ready to check anything against: the spec
+// is linted first, and a spec that fails or is blocked runs no station at all, exiting with lint's
+// own code (1 fail, 3 blocked) rather than a check-specific one. Passing lint's test 9 requires
+// improvement.ledger to be a non-empty path (see
+// src/rules.mjs), so by the time any station runs, the spec is guaranteed to declare one; the
+// presence check and escape check below exist anyway, for the same reason compare.mjs (the other
+// ledger writer) keeps its own copy: defense in depth costs one branch and this file should never
+// silently assume another file's invariant holds.
+
+import { appendFileSync, readFileSync } from "node:fs";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { loadSpec } from "./load.mjs";
+import { lintSpec } from "./rules.mjs";
+import { score, exitCode } from "./score.mjs";
+import { sha256 } from "./hash.mjs";
+import { insideDir } from "./fsutil.mjs";
+import { STATIONS, STATION_NAMES } from "./stations/index.mjs";
+import { str } from "./placeholder.mjs";
+
+const present = (v) => typeof v === "string" && v.trim().length > 0;
+
+// 1-based line array: text.split("\n"), so array index i holds line i + 1. A trailing "\r" (a
+// CRLF file) is stripped from every entry here, at the source, so every station that reads
+// draft.lines sees a clean line ("# Claim", never "# Claim\r") without needing to know CRLF
+// exists; the line COUNT and every 1-based line number are unaffected, since stripping a
+// trailing byte from an entry never changes how many entries there are.
+function splitLines(text) {
+  return text.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+}
+
+// Every well-formed kind: "check" line already in the ledger, in file order (oldest first). A
+// line that is not valid JSON, or not a kind: "check" object, is silently skipped here: this is a
+// read for verdict history, not a lint pass. A malformed ledger line is rules.mjs's test 9's
+// finding to report, not this function's to crash on.
+function priorCheckLines(text) {
+  return (text ?? "")
+    .split("\n")
+    .filter((l) => l.trim())
+    .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter((v) => v && typeof v === "object" && !Array.isArray(v) && v.kind === "check");
+}
+
+// A crash message with every absolute path in it made relative to the working directory, or cut to
+// "<path>/<file name>" when it lies outside it, so a station that hits a filesystem error never
+// prints this machine's layout.
+function withoutAbsolutePaths(message) {
+  return message.replace(/(?:[A-Za-z]:\\|\/)[^\s'"`,)]+/g, (p) => {
+    if (!isAbsolute(p)) return p;
+    const rel = relative(process.cwd(), p);
+    return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : `<path>/${basename(p)}`;
+  });
+}
+
+// runStation(station, spec, draft, ctx): runs one station's run(spec, draft, ctx), converting a
+// throw into a single failing finding rather than letting it crash the whole command. A station
+// is pure and deterministic BY CONTRACT, but that contract is not enforced by the type system,
+// and later stations (terms, claims, quotes, private, dna) read JSONL ledgers, segments files
+// and regexes over untrusted draft text, which is a lot more surface for a bug to throw from
+// than form's own narrow reading. A throw here must never crash the whole command (no raw stack
+// trace, no half-finished --json, no skipped ledger line): every OTHER station and the ledger
+// write still run normally, the same way lintSpec's own crash in bin/hyperspec.mjs's `lint`
+// handler becomes a reported error rather than an uncaught exception. Exported (and taking the
+// station object rather than reading STATIONS itself) so this exact wrapping is testable against
+// a station built to throw, without needing one registered in the shared registry
+// (src/stations/index.mjs), which this file does not own.
+export function runStation(station, spec, draft, ctx) {
+  try {
+    return station.run(spec, draft, ctx);
+  } catch (e) {
+    const raw = e instanceof Error ? e.message : String(e);
+    return {
+      station: station.name,
+      status: "fail",
+      findings: [{
+        station: station.name,
+        id: `station-${station.name}-crashed`,
+        severity: "fail",
+        message: withoutAbsolutePaths(raw),
+        fix: "Fix the station or file an issue; it should never throw.",
+      }],
+    };
+  }
+}
+
+// runCheck(specPathArg, draftPathArg, { only }): specPathArg and draftPathArg are exactly what
+// the CLI (or a caller) was given, never resolved, so every path this returns or writes to the
+// ledger is displayed and recorded the way the operator typed it, not as an absolute path on this
+// machine. only, when given, is an array of station names to run instead of every registered one.
+export function runCheck(specPathArg, draftPathArg, { only } = {}) {
+  if (!present(specPathArg)) return { usage: true, error: "check needs a spec path" };
+  if (!present(draftPathArg)) return { usage: true, error: "check needs --draft <file>" };
+
+  const spec = loadSpec(specPathArg);
+  if (spec.error) return { usage: true, error: spec.error };
+  // Every station reads the writing profile's blocks; a spec without it has nothing for them to
+  // read, and a run against it would fail quotations it has no materials for.
+  if (str(spec.data?.profile) !== "writing") return { usage: true, error: "check needs a writing spec (profile: writing)" };
+
+  // --only: every name must be one this build's registry knows; unknown names are a usage error
+  // (exit 2) rather than a silent no-op, and the run order always follows the registry, never the
+  // order --only happened to name them in, so two operators running the same --only string in a
+  // different order still see stations printed and ledgered identically.
+  let stationsToRun = STATIONS;
+  if (only && only.length) {
+    const unknown = only.filter((n) => !STATION_NAMES.includes(n));
+    if (unknown.length) {
+      return { usage: true, error: `unknown station${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}; known stations: ${STATION_NAMES.join(", ") || "(none)"}` };
+    }
+    stationsToRun = STATIONS.filter((s) => only.includes(s.name));
+  }
+
+  const lintFindings = lintSpec(spec);
+  const lintScore = score(lintFindings, spec.data);
+  if (lintScore.status !== "pass") {
+    return {
+      ok: false,
+      lintBlocked: true,
+      specPath: specPathArg,
+      lintStatus: lintScore.status,
+      lintScore,
+      lintFindings,
+      code: exitCode(lintScore.status),
+    };
+  }
+
+  let draftBuf;
+  try { draftBuf = readFileSync(resolve(draftPathArg)); }
+  catch { return { usage: true, error: `cannot read draft: ${draftPathArg}` }; }
+  // One leading UTF-8 BOM is not part of the draft's text: stripped here, so a heading on line 1
+  // is found and every offset and line number counts from the first real character. sha256 stays
+  // over the raw bytes.
+  const text = draftBuf.toString("utf8").replace(/^\uFEFF/, "");
+  const draft = { path: draftPathArg, text, lines: splitLines(text), sha256: sha256(draftBuf) };
+
+  const ctx = {};
+  const results = stationsToRun.map((s) => runStation(s, spec, draft, ctx));
+  const failing = results.filter((r) => r.status === "fail").map((r) => r.station);
+  const code = failing.length ? 1 : 0;
+
+  // ---- ledger: one line of evidence per check, only when the spec declares one -----------------
+  // What a line says, and why each reason is true:
+  //   - A run with --only is partial: verdict not-improved, reason "partial run: <stations>",
+  //     partial: true. Later verdicts ignore partial lines, so a subset never claims (or uses up)
+  //     the verdict for the whole draft.
+  //   - A full run compares with the most recent earlier FULL line for the same draft path (the
+  //     path relative to the spec's folder). "Changed" means the draft's bytes (draft_sha256) or
+  //     the spec's bytes (spec_sha256); files the spec names are not hashed.
+  //       none, and every station passes              -> one-shot
+  //       none, and a station fails                   -> not-improved "failing stations: X"
+  //       it failed, every station passes now         -> improved "stations now pass: X", exactly
+  //                                                      the stations that failed then and pass now
+  //       it passed, nothing changed, passing         -> not-improved "no change since the last passing check"
+  //       it passed, something changed, passing       -> not-improved "<what> changed; every station still passes"
+  //       failing now                                  -> not-improved "[<what> changed; |no change since
+  //                                                      the last check; ]still failing: X" when every
+  //                                                      failing station also failed then, else
+  //                                                      "[<what> changed; ]failing stations: X"
+  let ledgerPath = null;
+  let ledgerWarning = null;
+  let verdict = null;
+  let verdictDetail = {};
+  const partial = Boolean(only && only.length);
+  const ledgerDecl = spec.data?.improvement?.ledger;
+  if (present(ledgerDecl)) {
+    if (!insideDir(spec.dir, ledgerDecl)) {
+      ledgerWarning = "improvement.ledger escapes the spec's directory; not appended";
+    } else {
+      const ledgerAbs = resolve(spec.dir, ledgerDecl);
+      let priorText = "";
+      try { priorText = readFileSync(ledgerAbs, "utf8"); } catch { /* not written yet; a first check creates it */ }
+
+      // The draft as the ledger records it: relative to the spec's folder, with forward slashes, so
+      // "./draft.md", "draft.md" and an absolute path are one history, and no absolute path lands
+      // in a ledger that is usually committed.
+      const draftKey = relative(resolve(spec.dir), resolve(draftPathArg)).split(sep).join("/");
+      const specSha = sha256(readFileSync(resolve(specPathArg)));
+      const statusNow = Object.fromEntries(results.map((r) => [r.station, r.status]));
+      const list = (names) => names.join(", ");
+
+      if (partial) {
+        verdict = "not-improved";
+        verdictDetail.reason = `partial run: ${list(results.map((r) => r.station))}`;
+      } else {
+        const last = priorCheckLines(priorText).filter((l) => l.draft === draftKey && l.partial !== true).at(-1);
+        const failedThen = last ? Object.entries(last.stations ?? {}).filter(([, st]) => st === "fail").map(([n]) => n) : [];
+        const draftChanged = Boolean(last) && last.draft_sha256 !== draft.sha256;
+        const specChanged = Boolean(last) && last.spec_sha256 !== specSha;
+        const what = draftChanged && specChanged ? "spec and draft" : specChanged ? "spec" : draftChanged ? "draft" : null;
+        const passedNow = failing.length === 0;
+
+        if (!last) {
+          if (passedNow) verdict = "one-shot";
+          else { verdict = "not-improved"; verdictDetail.reason = `failing stations: ${list(failing)}`; }
+        } else if (passedNow && failedThen.length) {
+          const nowPass = failedThen.filter((n) => statusNow[n] === "pass");
+          if (nowPass.length) { verdict = "improved"; verdictDetail.change = `stations now pass: ${list(nowPass)}`; }
+          else { verdict = "not-improved"; verdictDetail.reason = `${what ? `${what} changed; ` : ""}stations that failed last time now skip: ${list(failedThen)}`; }
+        } else if (passedNow) {
+          verdict = "not-improved";
+          verdictDetail.reason = what ? `${what} changed; every station still passes` : "no change since the last passing check";
+        } else {
+          verdict = "not-improved";
+          const still = failing.every((n) => failedThen.includes(n));
+          const prefix = what ? `${what} changed; ` : still ? "no change since the last check; " : "";
+          verdictDetail.reason = `${prefix}${still ? "still failing" : "failing stations"}: ${list(failing)}`;
+        }
+      }
+
+      const line = {
+        at: new Date().toISOString(),
+        kind: "check",
+        draft: draftKey,
+        draft_sha256: draft.sha256,
+        spec_sha256: specSha,
+        stations: statusNow,
+        ...(partial ? { partial: true } : {}),
+        verdict,
+        ...verdictDetail,
+      };
+      appendFileSync(ledgerAbs, `${JSON.stringify(line)}\n`);
+      // Reported exactly as the spec wrote it (improvement.ledger's own string), never resolved.
+      ledgerPath = ledgerDecl;
+    }
+  }
+
+  return {
+    ok: true,
+    specPath: specPathArg,
+    draftPath: draftPathArg,
+    draftSha256: draft.sha256,
+    stations: results,
+    failing,
+    partial,
+    verdict,
+    verdictDetail,
+    ledgerPath,
+    ledgerWarning,
+    code,
+  };
+}