@supersuit/hyperspec 0.7.0 → 0.9.0

package/bin/hyperspec.mjs

@@ -19,13 +19,17 @@ import { str } from "../src/placeholder.mjs";
 import { runCheck } from "../src/check.mjs";
 import { prepareJudges, recordJudgment } from "../src/judge.mjs";
 import { prepareLearn, recordLearn, tallyLine } from "../src/learn.mjs";
+import { triageContext, triageState, answerFinding, importReview, replyText } from "../src/triage.mjs";
+import { sourceAt } from "../src/sequence-draft.mjs";
 
 const HELP = `hyperspec <command> [options]
 
   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
@@ -49,7 +53,10 @@ const HELP = `hyperspec <command> [options]
                                persona (against the claims ledger), and for fiction attribution (a
                                blind speaker test on the dialogue lines whose speaker the draft
                                names; the answers go to attribution.key.json, likewise rebuilt)
-                               and knowledge (each character's knowledge timeline);
+                               and knowledge (each character's knowledge timeline), and panel
+                               (one panel-<reader>.packet.json per reader: writing.panel's, or a
+                               skeptic, a novice and an expert, and always the audience's reader
+                               as buyer);
                                the same spec and draft give byte-identical packets; refuses to
                                overwrite an existing packet without --force
                                exit 0 written, 1 a station could not build its packet (the rest
@@ -63,7 +70,28 @@ const HELP = `hyperspec <command> [options]
                                verdict appends nothing; run it from the folder prepare ran in, since
                                the packet keeps the spec and draft paths as they were given
                                exit 0 the station passed, 1 it failed or the verdict is invalid
-                               or stale, 2 usage
+                               or stale, 2 usage; a panel verdict's improve, missing and remove
+                               items go to triage.jsonl, beside the runs ledger
+  triage status <spec> [--draft <file>] [--json]
+                               count the answers in the spec's triage.jsonl, list the passages two
+                               or more readers share, and hold every answer to the draft (as
+                               check's triage station does); without --draft a spec that lists
+                               writing.form.sequence.files reads them, as check does
+                               exit 0 it would pass, 1 it would fail, 2 usage
+  triage answer <spec> <finding> taken|kept|already-true|open [--evidence S] [--reason S]
+                [--draft <file>] [--json]
+                               answer one finding: taken and already-true need --evidence, a
+                               passage of the draft word for word; kept needs --reason
+                               exit 0 written, 1 refused (nothing written), 2 usage
+  triage import <spec> <review> [--source S] [--draft <file>] [--json]
+                               bring an outside review (markdown or plain text) in as findings;
+                               a heading names the reader, Good/Improve/Missing/Remove labels set
+                               the kind, each list item is a finding, praise is counted only
+                               exit 0 imported, 1 the review holds nothing to answer, 2 usage
+  triage reply <spec> [--source S] [--draft <file>] [--json]
+                               print a plain-text reply to the reviewer from the answers; it
+                               never sends anything
+                               exit 0 ready to send, 1 a finding is still unanswered, 2 usage
   learn prepare <spec> --first <draft> --approved <draft> --out <dir> [--force] [--json]
                                needs a writing spec that passes lint (exits with lint's own code
                                otherwise); diffs the first draft a factory produced against the
@@ -358,7 +386,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);
@@ -389,7 +416,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;
@@ -520,6 +547,110 @@ if (cmd === "learn") {
   process.exit(2);
 }
 
+if (cmd === "triage") {
+  const sub = argv[1];
+  const flags = {
+    status: { valueFlags: ["--draft"], boolFlags: ["--json"] },
+    answer: { valueFlags: ["--draft", "--evidence", "--reason"], boolFlags: ["--json"] },
+    import: { valueFlags: ["--draft", "--source"], boolFlags: ["--json"] },
+    reply: { valueFlags: ["--draft", "--source"], boolFlags: ["--json"] },
+  }[sub];
+  if (!flags) { console.error(`unknown triage subcommand: ${sub ?? "(none)"}\n\n${HELP}`); process.exit(2); }
+  const parsed = parseArgs(argv.slice(2), flags);
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [specPath, ...rest] = parsed.positionals;
+  const json = parsed.values["--json"];
+  const usage = (error) => {
+    if (json) console.log(JSON.stringify({ spec: specPath ?? null, draft: parsed.values["--draft"] ?? null, error }, null, 2));
+    else console.error(error);
+    process.exit(2);
+  };
+  const ctx = triageContext(specPath, parsed.values["--draft"], `triage ${sub}`);
+  if (ctx.usage) usage(ctx.error);
+  const { spec, draft } = ctx;
+  // A finding's line, named the way check names it: the file and its own line for a sequence.
+  const where = (f) => {
+    if (typeof f.line !== "number") return "";
+    const src = sourceAt(draft, f.line);
+    return src ? ` (${src.file} line ${f.line - src.startLine + 1})` : ` (line ${f.line})`;
+  };
+  const printFinding = (f) => console.log(`  ${f.severity === "fail" ? "fail" : "warn"} [${f.id}] ${f.message}${where(f)}\n    fix: ${f.fix}`);
+
+  if (sub === "status") {
+    const state = triageState(spec, draft);
+    if (state.skip) {
+      if (json) console.log(JSON.stringify({ spec: specPath, status: "skip", reason: state.skip }, null, 2));
+      else console.log(`triage: skip (${state.skip})`);
+      process.exit(0);
+    }
+    const status = state.findings.some((f) => f.severity === "fail") ? "fail" : "pass";
+    if (json) console.log(JSON.stringify({ spec: specPath, path: state.decl, status, counts: state.counts, shared: state.shared, findings: state.findings, items: state.items }, null, 2));
+    else {
+      const c = state.counts;
+      console.log(`${state.decl}: ${state.items.length} finding${state.items.length === 1 ? "" : "s"}; ${c.taken} taken, ${c.kept} kept, ${c["already-true"]} already true, ${c.open} open, ${c.unanswered} not answered`);
+      if (state.shared.length) {
+        console.log("shared by two or more readers:");
+        for (const g of state.shared) {
+          const line = where({ line: g.line }).replace(/^ \((.*)\)$/, "$1");
+          console.log(`  ${line}: "${g.passage}"`);
+          for (const f of g.findings) console.log(`    ${f.reader} (${f.kind}): ${f.text}`);
+        }
+      }
+      console.log(`triage: ${status}`);
+      for (const f of state.findings) printFinding(f);
+    }
+    process.exit(status === "pass" ? 0 : 1);
+  }
+
+  if (sub === "answer") {
+    const [findingId, disposition] = rest;
+    if (!findingId) usage("triage answer needs a finding id");
+    if (!disposition) usage("triage answer needs a disposition: taken, kept, already-true or open");
+    const result = answerFinding(spec, draft, findingId, disposition, { evidence: parsed.values["--evidence"], reason: parsed.values["--reason"] });
+    if (result.usage) usage(result.error);
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else if (result.invalid) {
+      console.log(`${findingId}: answer refused, nothing written`);
+      for (const f of result.findings) printFinding(f);
+    } else console.log(`${findingId}: ${disposition} (${result.path})`);
+    process.exit(result.code);
+  }
+
+  if (sub === "import") {
+    const [reviewPath] = rest;
+    if (!reviewPath) usage("triage import needs a review file");
+    let text;
+    try { text = readFileSync(resolve(reviewPath), "utf8"); } catch { usage(`cannot read review: ${reviewPath}`); }
+    const source = parsed.values["--source"] ?? reviewPath;
+    const result = importReview(spec, draft, text, source);
+    if (result.usage) usage(result.error);
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else if (result.invalid) {
+      console.log(`${reviewPath}: nothing imported`);
+      for (const f of result.findings) printFinding(f);
+    } else {
+      console.log(`${source}: ${result.added} finding${result.added === 1 ? "" : "s"} added to triage (${result.path})${result.already ? `, ${result.already} already there` : ""}${result.praise ? `; ${result.praise} item${result.praise === 1 ? "" : "s"} of praise, not triaged` : ""}`);
+      for (const f of result.warnings) printFinding(f);
+    }
+    process.exit(result.code);
+  }
+
+  if (sub === "reply") {
+    const state = triageState(spec, draft);
+    if (state.skip) usage(`nothing to reply to: ${state.skip}`);
+    const source = parsed.values["--source"];
+    const reply = replyText(state.items, source);
+    if (!reply.count) usage(`no finding in ${state.decl} comes from ${source}`);
+    const failing = state.findings.filter((f) => f.severity === "fail");
+    if (json) console.log(JSON.stringify({ spec: specPath, source: source ?? null, text: reply.text, unanswered: reply.unanswered, ready: !failing.length }, null, 2));
+    else {
+      process.stdout.write(reply.text);
+      if (failing.length) console.error(`not ready to send: triage fails (${failing.length} finding${failing.length === 1 ? "" : "s"}); run hyperspec triage status`);
+    }
+    process.exit(failing.length ? 1 : 0);
+  }
+}
+
 // A spec that does not lint clean: print what lint would, say nothing was written, and exit with
 // lint's own code. Shared by judge prepare and learn prepare.
 function printLintBlocked(result, json, nothingWritten) {

package/examples/writing/course/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,64 @@
+---
+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.
+
+## Check yourself: Part 1
+
+1. *(Lesson 1)* Five hundred grams of flour and four hundred of water: what is the hydration?
+   - a) Forty percent
+   - b) Eighty percent
+2. *(Lesson 1)* When is flour and water a dough?
+   - a) When no dry flour is left
+   - b) When it has doubled
+3. *(Lesson 2)* What does a starter need every day?
+   - a) A pinch of salt
+   - b) A feed of flour and water
+4. *(Lesson 2)* How do you tell a proof is done?
+   - a) A finger dent fills back slowly
+   - b) The top has cracked
+
+**Answers:** 1 b · 2 a · 3 b · 4 a
+
+---
+
+**Next, Part 2: The bake.** Shaping a loaf that holds itself up, and what happens to the crumb in the oven.

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

@@ -0,0 +1,57 @@
+---
+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.
+
+## Check yourself: Part 2
+
+1. *(Lesson 3)* Why give a dough a bench rest?
+   - a) So it relaxes enough to be shaped again
+   - b) So it cools down
+2. *(Lesson 3)* What lets a shaped loaf stand instead of spreading?
+   - a) More water
+   - b) Surface tension
+3. *(Lesson 4)* When does oven spring happen?
+   - a) In the first ten minutes of heat
+   - b) While the loaf cools
+4. *(Lesson 4)* A tight, even crumb with a dense band at the bottom means what?
+   - a) The oven was too hot
+   - b) The proof was too short
+
+**Answers:** 1 a · 2 b · 3 a · 4 b

package/examples/writing/course.hyperspec.md

@@ -0,0 +1,206 @@
+---
+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,
+      quiz: Check yourself
+    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.