@supersuit/hyperspec 0.6.0 → 0.8.0

package/bin/hyperspec.mjs

@@ -17,13 +17,17 @@ 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
+  check <spec> [--draft <file>] [--json] [--only a,b]
+                               needs a writing spec (profile: writing), and --draft unless the
+                               spec lists writing.form.sequence.files, whose files, joined in
+                               reading order, are then the draft; 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
@@ -35,6 +39,53 @@ const HELP = `hyperspec <command> [options]
                                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,
@@ -309,7 +360,6 @@ if (cmd === "check") {
     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);
@@ -340,7 +390,7 @@ if (cmd === "check") {
     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}`);
+      for (const finding of s.findings) console.log(`  ${finding.severity === "fail" ? "fail" : "warn"} [${finding.id}] ${finding.message}${typeof finding.line === "number" ? ` (${finding.file ? `${finding.file} ` : ""}line ${finding.line})` : ""}\n    fix: ${finding.fix}`);
     }
     if (result.verdict) {
       const detail = result.verdictDetail.change ?? result.verdictDetail.reason;
@@ -351,6 +401,140 @@ if (cmd === "check") {
   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/course/goldens/lesson.md

@@ -0,0 +1 @@
+Mix the flour and the water with your hand until no dry flour is left. It will look wrong. It is supposed to look wrong. Leave it for half an hour and come back.

package/examples/writing/course/materials/brief.md

@@ -0,0 +1,9 @@
+Course brief, written by the author after teaching the class twice.
+
+Nobody who has never baked needs a recipe first. They need four words they do not have yet: dough, starter, proof and crumb. Every class that went badly went badly because I used one of those words before I had said what it meant.
+
+The order matters more than the recipes. Water and flour first, then what makes it rise, then shaping, then the oven. Each lesson should stand only on the ones before it.
+
+Each lesson ends with one thing to do in a real kitchen, because nobody learns bread by reading about it.
+
+I once taught shaping before proofing and half the room shaped dough that had not risen. I never did it again.

package/examples/writing/course/materials/brief.md.segments.jsonl

@@ -0,0 +1,6 @@
+{"material":"brief","path":"course/materials/brief.md","sha256":"7fc69cebae3218131d8e920af1408b42505ebfe2ccb4f72e9eb9c9ac9fb48b24"}
+{"id":"s1","start":0,"end":67,"label":"aside","text":"Course brief, written by the author after teaching the class twice."}
+{"id":"s2","start":69,"end":299,"label":"claim","own":true,"text":"Nobody who has never baked needs a recipe first. They need four words they do not have yet: dough, starter, proof and crumb. Every class that went badly went badly because I used one of those words before I had said what it meant."}
+{"id":"s3","start":301,"end":471,"label":"claim","own":true,"text":"The order matters more than the recipes. Water and flour first, then what makes it rise, then shaping, then the oven. Each lesson should stand only on the ones before it."}
+{"id":"s4","start":473,"end":578,"label":"stance","text":"Each lesson ends with one thing to do in a real kitchen, because nobody learns bread by reading about it."}
+{"id":"s5","start":580,"end":690,"label":"story","teller":"example-author","text":"I once taught shaping before proofing and half the room shaped dough that had not risen. I never did it again."}

package/examples/writing/course/outline.md

@@ -0,0 +1,11 @@
+# Bread from zero: the outline
+
+## Part 1: Dough
+
+1. **Flour and water.** What happens when the two meet. *Terms: dough, hydration.*
+2. **What makes it rise.** A living culture you keep in a jar. *Terms: starter, proof.*
+
+## Part 2: The bake
+
+3. **Shaping.** Turning a slack mass into a loaf that holds itself up. *Terms: bench rest, surface tension.*
+4. **The oven.** What heat does in the first ten minutes, and how to read the inside. *Terms: oven spring, crumb.*

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

@@ -0,0 +1,47 @@
+---
+title: "Bread from zero, Part 1: Dough"
+---
+
+# Bread from zero
+
+## Part 1: Dough
+
+This course assumes you have never baked a loaf. Every word it needs is defined in the lesson that first uses it.
+
+---
+
+## Lesson 1: Flour and water
+
+**After this lesson you can:** mix a dough and say how wet it is.
+
+**New terms:**
+- **Dough:** flour and water mixed until no dry flour is left.
+- **Hydration:** how much water a dough holds for its flour, as a share of the flour's weight. Five hundred grams of flour and three hundred and fifty of water is seventy percent.
+
+Put five hundred grams of flour in a bowl and pour in three hundred and fifty grams of water. Mix with your hand until nothing dry is left. That is a dough.
+
+It will look wrong: shaggy, sticky, nothing like bread. Leave it covered for half an hour. The water is still working its way into the flour, and when you come back the dough will be smoother without your having done anything.
+
+The higher the hydration, the stickier the dough and the more open the bread. Seventy percent is a forgiving place to start. Lesson 4 shows you what hydration does inside a finished loaf.
+
+**Try this:** mix one dough at sixty percent and one at seventy-five, and press a finger into each after half an hour.
+
+---
+
+## Lesson 2: What makes it rise
+
+**After this lesson you can:** keep a starter alive and tell when a dough has risen enough.
+
+**New terms:**
+- **Starter:** flour and water left to ferment, kept in a jar and fed every day. It is what makes the dough rise.
+- **Proof:** the rise itself, the hours a dough spends growing before it is shaped and baked.
+
+Mix fifty grams of flour and fifty of water in a jar, loosely covered. Feed it the same again every day. In about a week it will double within hours of a feed and smell sour. It is alive, and it is ready.
+
+Add a spoon of starter to the dough from Lesson 1 and leave it somewhere warm. The dough is now proofing. It is done when it has grown by half and a finger pressed into it leaves a dent that fills back slowly.
+
+**Try this:** start a starter today, and mark the jar with tape at its height after each feed.
+
+---
+
+**Next, Part 2: The bake.** Shaping a loaf that holds itself up, and what happens to the crumb in the oven.

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

@@ -0,0 +1,40 @@
+---
+title: "Bread from zero, Part 2: The bake"
+---
+
+# Bread from zero
+
+## Part 2: The bake
+
+Part 1 made a dough and made it rise. This part turns it into bread.
+
+---
+
+## Lesson 3: Shaping
+
+**After this lesson you can:** shape a proofed dough into a loaf that holds itself up.
+
+**New terms:**
+- **Bench rest:** twenty minutes a dough sits on the counter between a rough shape and the final one, so it relaxes enough to be shaped again.
+- **Surface tension:** the tight skin you pull across the top of a loaf, which is what lets it stand instead of spreading.
+- **Dough** (from Lesson 1): flour and water mixed until no dry flour is left.
+
+Tip the proofed dough onto the counter and fold it into a rough ball. Give it a bench rest. Then flip it, fold the far edge to the middle, and roll it toward you, pulling the top tight as you go. That tightness is surface tension, and a loaf without it spreads in the oven.
+
+**Try this:** shape two loaves, one pulled tight and one left loose, and bake them side by side after Lesson 4.
+
+---
+
+## Lesson 4: The oven
+
+**After this lesson you can:** bake a loaf and read what its inside tells you.
+
+**New terms:**
+- **Oven spring:** the last rise a loaf takes in the first ten minutes of heat, before the crust sets.
+- **Crumb:** the inside of a baked loaf: the holes, their size, and how they are spread.
+
+Heat the oven as hot as it goes, with a heavy pot inside. Put the loaf in the pot, cover it, and bake for twenty minutes, then uncover it and bake until it is dark. The covered minutes are the oven spring: steam keeps the crust soft while the loaf grows.
+
+Let it cool for an hour before you cut it. Then read the crumb. Big uneven holes mean a well proofed, high hydration dough. A tight, even crumb with a dense band at the bottom means the proof was too short.
+
+**Try this:** cut the two loaves from Lesson 3 and compare their crumb.

package/examples/writing/course.hyperspec.md

@@ -0,0 +1,205 @@
+---
+hyperspec: "0.1"
+title: "Bread from zero: a four-lesson course"
+kind: course
+profile: writing
+decisions:
+  - id: kind
+    state: decided
+    value: a course of four lessons in two parts, for someone who has never baked a loaf
+    source: course/materials/brief.md
+    author: example-author
+    chosen_by: human
+  - id: lesson-shape
+    state: decided
+    value: every lesson opens with what the reader can do after it and the terms it defines, and ends with one thing to do in a kitchen
+    source: course/materials/brief.md, the paragraph on ending each lesson
+    author: example-author
+    chosen_by: human
+  - id: part-files
+    state: delegated
+    rule: one file per part, named part-<n>.md, so a new part is picked up by the files pattern without editing the spec
+    source: course layout
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: no lesson uses a term before the lesson that defines it
+    fails_when: the sequence station reports a term used before it is defined
+    check:
+      station: sequence station, order guard
+    source: course/materials/brief.md
+    author: example-author
+  - id: r2
+    text: every term is defined in exactly one lesson
+    fails_when: the sequence station reports a term defined twice
+    check:
+      station: sequence station, defined-once guard
+    source: lesson-shape decision
+    author: example-author
+  - id: r3
+    text: every lesson carries its three sections
+    fails_when: a lesson has no "After this lesson you can", "New terms" or "Try this" section
+    check:
+      station: sequence station, sections guard
+    source: lesson-shape decision
+    author: example-author
+  - id: r4
+    text: each lesson defines the terms the outline promises for it
+    fails_when: the outline promises a term in a lesson that does not define it
+    check:
+      station: sequence station, outline guard
+    source: course/outline.md
+    author: example-author
+  - id: r5
+    text: every Try this can be done in a home kitchen in one day, apart from the starter, which takes a week
+    fails_when: a Try this needs equipment beyond a bowl, a scale, a jar, an oven and a heavy pot
+    check:
+      rubric: list what each Try this needs; fail on anything outside that list
+    source: course/materials/brief.md
+    author: example-author
+rejects:
+  - a recipe before the reader has the words to follow it
+  - a term used before the lesson that defines it
+examples:
+  - path: course/goldens/lesson.md
+    why: an instruction, then the reader's likely worry named plainly, then what to do next
+resume:
+  next_action: bake the course's two loaves from Lesson 3 and photograph their crumb for Lesson 4
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: course/runs.jsonl
+writing:
+  materials:
+    items:
+      - id: brief
+        path: course/materials/brief.md
+        segments: course/materials/brief.md.segments.jsonl
+        produced_by: example-author
+        captured: "2026-09-20"
+        how: written after teaching the class twice
+        trust: considered
+    check:
+      station: every segment of every material carries a label from the closed set, matches its source verbatim, and the markings are current
+    source: capture step
+    author: agent:claude
+  dna:
+    writer: example-author
+    scope:
+      form: course
+      audience: first-time bakers
+      purpose: teach
+    rules: style-rules.md
+    goldens:
+      - path: course/goldens/lesson.md
+        why: an instruction, then the reader's likely worry named plainly, then what to do next
+    check:
+      rubric: blind lineup within this scope
+    source: goldens marked on the review page
+    author: example-author
+  persona:
+    identity: self
+    stance: guide
+    may_assert:
+      - what the author saw go wrong when teaching the class
+    will_not_say:
+      - a bake time or temperature for an oven the author has not used
+    facts_from: sources
+    check:
+      rubric: persona-consistency judge
+    source: persona interview
+    author: example-author
+  audience:
+    who: someone who has never baked a loaf of bread
+    funnel_now: has bought flour and has never used it for bread
+    knows:
+      - flour
+      - oven
+    believes_now: bread takes a recipe and a lot of skill
+    wants: to bake one good loaf
+    reads_on: a tablet propped up in the kitchen
+    reader: person
+    check:
+      station: the sequence station defines every term before it is used
+      rubric: simulated reader reports where it got lost
+    source: audience interview
+    author: example-author
+  goal:
+    from: has never baked bread
+    to: bakes a loaf and reads its crumb
+    next_if_worked: starts a starter the day they finish Lesson 2
+    change:
+      kind: action
+      text: the reader bakes their first loaf
+    conditions: [r1, r2, r3, r4, r5]
+    check:
+      rubric: the doctor grades the course against every condition
+    source: goal interview
+    author: example-author
+  form:
+    name: course
+    length:
+      min: 400
+      max: 1500
+      unit: words
+    required_parts:
+      - "Part 1: Dough"
+      - "Part 2: The bake"
+    stations:
+      - the sequence station
+    sequence:
+      unit: Lesson
+      files:
+        - course/part-*.md
+      sections:
+        - After this lesson you can
+        - New terms
+        - Try this
+      terms_section: New terms
+      outline: course/outline.md
+      teaser: Next,
+    check:
+      station: structure and length, then the sequence station
+    source: form decision
+    author: example-author
+  spine:
+    kind: primer
+    claims:
+      - id: c1
+        text: a first-time baker needs four words before any recipe
+        materials: [brief#s2]
+      - id: c2
+        text: the order is water and flour, then the rise, then shaping, then the oven
+        materials: [brief#s3]
+      - id: c3
+        text: each lesson ends with something to do in a real kitchen
+        materials: [brief#s4, brief#s5]
+    check:
+      rubric: each claim lands, in order
+    source: spine interview
+    author: example-author
+  sources:
+    ledger: course/claims.jsonl
+    unsourced_claim: fail
+    check:
+      station: every factual claim in the ledger points at a source span
+    source: sourcing pass
+    author: agent:claude
+fiction: false
+---
+
+# Bread from zero
+
+A worked example of a sequential work: a course of four lessons in two parts, one file per part.
+The spec lists the parts as `course/part-*.md`, so `check` needs no `--draft`: the parts, joined
+in order, are the draft.
+
+```bash
+npx @supersuit/hyperspec check course.hyperspec.md
+```
+
+The `sequence` station holds the course to what a reader of Lesson 3 depends on: Lessons 1 and 2
+defined every word it uses. The outline in `course/outline.md` promises the terms each lesson
+defines, and the station checks the lessons keep that promise.