@supersuit/hyperspec 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.8.0 (2026-09-29)
+
+A work read in order can now be checked as one. Every station so far held ONE piece to its spec; a
+course, a primer or a textbook makes promises ACROSS its pieces (Lesson 5 is written for someone who
+has read Lessons 1 to 4 and nothing else), and nothing checked them. Declare `writing.form.sequence`
+and the new `sequence` station does, deterministically, on every `check`. Promoted from a checker
+written for one book, so every sequential work gets it by construction.
+
+- `writing.form.sequence`, optional, every key optional: `unit` (the heading word, default
+  `Lesson`), `files` (the work's files in reading order; a `*` in a file name matches, sorted by
+  number), `sections` (default "After this lesson you can", "New terms", "Try this"),
+  `terms_section` (default "New terms"), `outline` (numbered items promising `*Terms: a, b.*`),
+  `knows` (words a lesson may use before one defines them, beside `audience.knows`) and `teaser`
+  (default "Next,": a closing line naming what is coming). Lint refuses a key that is present and
+  hollow under test 1, and a `files` entry matching nothing or an `outline` that is not a file under
+  test 6.
+- The `sequence` station, run last: every unit carries its sections; every term is defined in
+  exactly one unit; no unit uses a term before the unit that defines it (code, the unit's own terms
+  section and its closing teaser are not uses, and a `(from Lesson N)` reminder defines nothing);
+  each unit defines what the outline promises, for the units the draft holds; unit numbers increase;
+  a pointer to a later unit is a warning. Findings: `station-sequence-no-units`, `-numbering`,
+  `-missing-section`, `-defined-twice`, `-used-before-defined`, `-outline-unreadable`,
+  `-outline-unkept` (fail) and `-forward-pointer` (warn). A spec with no `sequence` skips it.
+- `hyperspec check <spec>` needs no `--draft` when the spec lists `sequence.files`: the files,
+  joined in order with each one's frontmatter blanked, are the draft, and every station reads them.
+  A finding names the file and its own line (`(course/part-1.md line 25)`; `file` and `line` in
+  `--json`), a relative link resolves beside the file that holds it, and the ledger keys the run by
+  the `files` entry as written, so the work keeps one history as parts are added. `--draft` still
+  names one file, which may hold every lesson.
+- A third worked example, `examples/writing/course.hyperspec.md`: four lessons in two part files
+  with an outline, passing every station with two forward-pointer warnings.
+
+**Behavior change:** `check` runs eight stations, so `--json` and the ledger's `stations` carry
+`sequence` (as `skip` for every spec without a sequence). No other station, finding id or schema
+field changed, and a 0.7 ledger's verdicts read as they did.
+
 ## 0.7.0 (2026-09-29)
 
 A spec can now have its judgments made and recorded. `check` covers what a function of the spec

package/README.md

@@ -28,7 +28,7 @@ improvement ledger. Every test is defined in [SPEC.md](SPEC.md).
 | `hyperspec segments init <material> --id <mid> [--out F] [--by paragraph\|sentence]` | Split a material into segments to label. Refuses to overwrite an existing file. |
 | `hyperspec dna init <scope-dir> --writer W --form F --audience A --purpose P` | Start a writer-DNA scope folder. Refuses to overwrite an existing `scope.md`. |
 | `hyperspec dna measure <scope-dir>` | Check every golden in a scope and write its measured features. |
-| `hyperspec check <spec> --draft <file> [--only a,b]` | Run a writing spec's deterministic stations against a draft. |
+| `hyperspec check <spec> [--draft <file>] [--only a,b]` | Run a writing spec's deterministic stations against a draft, or, for a sequential work, against its files in reading order. |
 | `hyperspec judge prepare <spec> --draft <file> --out <dir> [--only a,b] [--force]` | Write one packet per judgment station, for an outside judge to fill. |
 | `hyperspec judge record <packet> --verdict <file>` | Check a judge's verdict against its packet, derive the station's status, and record it. |
 | `hyperspec learn prepare <spec> --first <draft> --approved <draft> --out <dir> [--force]` | Write the edits between a first draft and the approved one, for a judge to classify by spec block. |
@@ -145,9 +145,10 @@ npx @supersuit/hyperspec init story.hyperspec.md --profile writing --form "short
 
 The skeleton fails until every placeholder is real and its four open questions (whose voice,
 who speaks, who reads, what changes) are answered. The blocks, every field, and which test
-each rule reports under are in [WRITING.md](WRITING.md). Two complete specs that pass with
-nothing to warn ship in `examples/writing/`: an essay for new managers, and a short story with
-two characters whose voices a judge can tell apart. Each comes with a draft written to it.
+each rule reports under are in [WRITING.md](WRITING.md). Three complete specs that pass with
+nothing to warn ship in `examples/writing/`: an essay for new managers, a short story with
+two characters whose voices a judge can tell apart, and a four-lesson course. Each comes with a
+draft written to it.
 
 ### Marking materials
 
@@ -193,23 +194,48 @@ it did in 0.4. The folder shape, every feature, and every finding are in
 
 ### Checking a draft
 
-Once a draft exists, `check` holds it to its spec with seven stations, none of which calls a
+Once a draft exists, `check` holds it to its spec with eight stations, none of which calls a
 model or touches the network: `form` (length and required parts), `terms` (every word in the new
 optional `writing.audience.terms` is defined where it first appears), `claims` (the claims
 ledger still matches the draft, and every claim has a source), `quotes` (in nonfiction, every quotation of four
 words or more is word for word in a marked quote), `private` (no run of eight words from a
-private segment), `dna` (the draft's measured style beside its scope's, as warnings) and `links`
-(well-formed, and relative links resolve).
+private segment), `dna` (the draft's measured style beside its scope's, as warnings), `links`
+(well-formed, and relative links resolve) and `sequence` (for a work read in order; see below).
 
 ```bash
 npx @supersuit/hyperspec check essay.hyperspec.md --draft essay/draft.md
 ```
 
 It lints the spec first, prints each station's pass, fail or skip, and appends one line to the
-spec's runs ledger with a verdict. Both examples ship a draft that passes. What each station
+spec's runs ledger with a verdict. Every example ships a draft that passes. What each station
 checks and cannot check, and every finding, are in
 [WRITING.md](WRITING.md#checking-a-draft).
 
+### Sequential works
+
+A course, a primer or a textbook promises something no single piece can check: Lesson 5 uses only
+words Lessons 1 to 4 defined. Add `sequence:` to `writing.form` and the `sequence` station checks
+it across the whole work: every lesson carries its sections ("After this lesson you can", "New
+terms", "Try this" by default), every term is defined in exactly one lesson, no lesson uses a term
+before the lesson that defines it (code, the part's closing teaser and words the reader already
+knows are exempt), each lesson defines the terms the outline promises, and a pointer to a later
+lesson is a warning. List the work's files and `check` needs no `--draft`:
+
+```yaml
+    sequence:
+      files:
+        - course/part-*.md
+      outline: course/outline.md
+```
+
+```bash
+npx @supersuit/hyperspec check course.hyperspec.md
+```
+
+The parts are read in order, a finding names the part and its line, and a new part matching the
+pattern is picked up without touching the spec. Every key, how a lesson is read, and every finding
+are in [WRITING.md](WRITING.md#sequential-works).
+
 ### Judging a draft and learning from edits
 
 The rest of a spec's checks are judgments: whether each goal condition holds, where a reader gets

package/SPEC.md

@@ -109,7 +109,7 @@ improvement:
 
 A person writing for another person leaves most of the specification unsaid, because the other person fills the gaps from shared context. An agent has none of that context, so it fills every gap with the average, and the average is what reads as middling. Hyperspecification is writing down the gaps. It is a level of detail that would feel like overkill between two people and is exactly enough for an agent: every decision the agent would otherwise guess is either decided, delegated with the rule for deciding it, or marked open, so the work stops instead of guessing.
 
-**Version 0.7.0** (2026-09-29)
+**Version 0.8.0** (2026-09-29)
 
 ## What makes a spec a hyperspec
 

package/WRITING.md

@@ -245,6 +245,10 @@ writing:
       - a close
     stations:                        # may be empty
       - the three questions render as a numbered list
+    sequence:                        # optional: a work read in order; see Sequential works
+      files:                         # optional: its files in reading order; a * in a file name matches
+        - course/part-*.md
+      outline: course/outline.md     # optional: the outline that promises each unit's terms
     check:
       station: structure and length check
     source: form decision
@@ -337,12 +341,12 @@ Each row lists what the writing profile adds to that test. The core conditions i
 
 | Test | A writing spec fails it when |
 |---|---|
-| 1 every decision is accounted for | a required block is missing and not deferred; a required field is missing; a closed-set value is outside its set (`trust`, `reader`, `change.kind`, the shape of `identity`, `unsourced_claim`); `identity: character:<id>` names a character that is not in `writing.characters`; `fiction` is present and is anything other than `true` or `false`; two materials, two spine claims or two characters share an id; `form.length.min` or `max` is not a whole number of at least 1, or `min` is greater than `max`; `spine.claims` has fewer than three or more than seven distinct claims; a character has no knowledge entry, or an entry lacks `by` or `knows`; a material has no text, or no `segments` field, or its segments file is missing, malformed, labels a segment outside the seven (`unlabeled` included), repeats a segment id, or has segments that overlap or leave text uncovered; `dna.scope_dir` is present and is a placeholder; with `dna.scope_dir`, its `scope.md` is missing, unreadable or lacks a field, its writer, form, audience or purpose differs from the spec's, or its `goldens/` folder is missing or empty, or holds a golden that cannot be read, whose frontmatter never closes, or that has no passage; `audience.terms`, when present, holds a non-string entry or has no real entries at all. A `stance` outside the four is a warning, and so is `unsourced_claim: warn` |
+| 1 every decision is accounted for | a required block is missing and not deferred; a required field is missing; a closed-set value is outside its set (`trust`, `reader`, `change.kind`, the shape of `identity`, `unsourced_claim`); `identity: character:<id>` names a character that is not in `writing.characters`; `fiction` is present and is anything other than `true` or `false`; two materials, two spine claims or two characters share an id; `form.length.min` or `max` is not a whole number of at least 1, or `min` is greater than `max`; `spine.claims` has fewer than three or more than seven distinct claims; a character has no knowledge entry, or an entry lacks `by` or `knows`; a material has no text, or no `segments` field, or its segments file is missing, malformed, labels a segment outside the seven (`unlabeled` included), repeats a segment id, or has segments that overlap or leave text uncovered; `dna.scope_dir` is present and is a placeholder; with `dna.scope_dir`, its `scope.md` is missing, unreadable or lacks a field, its writer, form, audience or purpose differs from the spec's, or its `goldens/` folder is missing or empty, or holds a golden that cannot be read, whose frontmatter never closes, or that has no passage; `audience.terms`, when present, holds a non-string entry or has no real entries at all; `form.sequence` is present and is not a map, or has `unit`, `terms_section`, `teaser` or `outline` empty or a placeholder, or has `files`, `sections` or `knows` that is not a list of real entries. A `stance` outside the four is a warning, and so is `unsourced_claim: warn` |
 | 2 every requirement can fail | `goal.conditions` lists fewer than five or more than ten distinct ids, lists an id twice, or names an id that is not a top-level requirement |
 | 3 every requirement names its check | a block or a character has no `check` with a `station` or a `rubric` |
 | 4 every field says where it came from and who wrote it | a block or a character has no `source` or no `author`; a spine claim names no materials, or names a material id that is not in `materials.items`, or a segment that is not in that material's segments file; a segment's text does not match its material word for word; a material changed after it was marked; a claim segment has no `source` and no `own`, a story no `teller`, a quote no `speaker`; with `dna.scope_dir`, a golden in the scope has no `approved_by`, an approver that starts `agent:`, or no `source` |
 | 5 negative space is specified | `persona.will_not_say` is empty; `persona.facts_from` is anything other than `sources`; a spine claim cites a `private` or a `question` segment; with `dna.scope_dir`, a golden the spec lists is not one of the scope's goldens (it lives outside the scope's `goldens/` folder, is a symlink that resolves outside it, or sits in a subfolder, is `README.md` or is not a `.md` file), or the scope's `goldens/` folder resolves outside the scope |
-| 6 examples outrank adjectives | a golden has no `why`; a material, `dna.rules`, golden or character `entity` path does not exist or is not a file; a character has no golden lines or no rejected lines, or has the same line in both (compared trimmed and case-folded); with `dna.scope_dir`, a golden in the scope has no `why`, or the scope's `features.json` is missing or is not what `dna measure` would write now |
+| 6 examples outrank adjectives | a golden has no `why`; a material, `dna.rules`, golden, character `entity` or `form.sequence.outline` path does not exist or is not a file; a `form.sequence.files` entry matches no file; a character has no golden lines or no rejected lines, or has the same line in both (compared trimmed and case-folded); with `dna.scope_dir`, a golden in the scope has no `why`, or the scope's `features.json` is missing or is not what `dna measure` would write now |
 | 7 a stranger can resume it | `writing.progress` exists. An unknown `profile:` is a warning |
 | 8 its adopters can push back on it | nothing further; the core rule applies |
 | 9 it improves itself | nothing further; the core rule applies |
@@ -810,7 +814,7 @@ npx @supersuit/hyperspec check essay.hyperspec.md --draft essay/draft.md
 
 It lints the spec first. A spec that fails lint, or is blocked on an open decision, runs no
 station and exits with lint's own code, because a draft cannot be checked against a spec that is
-not ready. Then it runs seven stations in a fixed order and prints one line for each: `pass`,
+not ready. Then it runs eight stations in a fixed order and prints one line for each: `pass`,
 `fail` with its findings, or `skip` with the reason. A warning prints under its station and never
 fails it. This is the essay example's draft:
 
@@ -824,6 +828,7 @@ dna: pass
   warn [station-dna-drift] first_person_singular_rate is 22.892 in the draft; the scope's goldens measure 0, band 0 to 5
     fix: Bring first_person_singular_rate back inside the band, or, if the scope no longer describes this writer, re-measure it with better goldens.
 links: pass
+sequence: skip (the spec declares no writing.form.sequence)
 verdict: one-shot
 ```
 
@@ -832,10 +837,13 @@ marked partial (see [The runs ledger](#the-runs-ledger)). `--json` prints the wh
 finding included; a spec that is not ready prints lint's result with `lintBlocked: true` instead,
 and a usage error prints `{ "spec", "draft", "error" }`. A finding names the draft line it points
 at where there is one, quotes at most 80 characters of the draft, and never prints an absolute
-path. A UTF-8 byte order mark at the start of the draft is ignored.
+path. A UTF-8 byte order mark at the start of the draft is ignored. A spec that lists
+`form.sequence.files` needs no `--draft`: its files, joined in reading order, are the draft, and a
+finding names the file and its own line in it (see [Sequential works](#sequential-works)).
 
 Exit codes: **0** every station that ran passed (a skip or a warning does not fail it); **1** a
-station failed; **2** usage: no spec path, no `--draft`, a draft that cannot be read, a spec
+station failed; **2** usage: no spec path, no `--draft` for a spec that lists no
+`form.sequence.files`, a draft that cannot be read, a spec
 without `profile: writing`, or an `--only` that names no known station; and lint's own **1** or
 **3** when the spec is not ready.
 
@@ -973,6 +981,25 @@ the network, so it cannot tell you a URL is live.
 | `station-links-root-relative` | warn | a link starting with `/`, which cannot be resolved without the site |
 | `station-links-undefined-reference` | fail | a full or collapsed reference link whose label has no definition |
 
+### sequence
+
+Runs when the spec declares `form.sequence`, and holds a work read in order to what its reader
+depends on: every lesson carries its sections, every term is defined once, no lesson uses a term
+before the lesson that defines it, and each lesson defines what the outline promises. How a unit is
+read, and each guard, are under [Sequential works](#sequential-works). With no `form.sequence` the
+station skips. It reads words, never meaning: a term used in another sense still counts as a use.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-sequence-no-units` | fail | the draft has no `<unit> <n>` heading |
+| `station-sequence-numbering` | fail | a unit's number is not greater than the one before it |
+| `station-sequence-missing-section` | fail | a unit lacks one of `sections`; names the unit and the section |
+| `station-sequence-defined-twice` | fail | a term is defined in two units' terms sections; names both |
+| `station-sequence-used-before-defined` | fail | a unit uses a term before the unit that defines it; points at the first use |
+| `station-sequence-outline-unreadable` | fail | `outline` is set and the file cannot be read |
+| `station-sequence-outline-unkept` | fail | the outline promises a term in a unit that does not define it |
+| `station-sequence-forward-pointer` | warn | a unit mentions a later unit by number, once per pair |
+
 ### Any station
 
 | Id | Severity | Meaning |
@@ -985,11 +1012,13 @@ Each `check` appends one line to the spec's `improvement.ledger`, the same file
 reads:
 
 ```json
-{"at":"2026-09-29T13:21:37.330Z","kind":"check","draft":"essay/draft.md","draft_sha256":"<sha256 of the draft>","spec_sha256":"<sha256 of the spec>","stations":{"form":"pass","terms":"pass","claims":"pass","quotes":"pass","private":"pass","dna":"pass","links":"pass"},"verdict":"one-shot"}
+{"at":"2026-09-29T13:21:37.330Z","kind":"check","draft":"essay/draft.md","draft_sha256":"<sha256 of the draft>","spec_sha256":"<sha256 of the spec>","stations":{"form":"pass","terms":"pass","claims":"pass","quotes":"pass","private":"pass","dna":"pass","links":"pass","sequence":"skip"},"verdict":"one-shot"}
 ```
 
 `draft` is the draft's path relative to the spec's folder, however you spelled it, so one draft
-has one history. `draft_sha256` and `spec_sha256` hash the two files' bytes; the files the spec
+has one history. A work checked from `form.sequence.files` is keyed by that list as the spec writes
+it, joined with ", ", so the work keeps one history as parts are added, and its `draft_sha256`
+covers every file's name and bytes. `draft_sha256` and `spec_sha256` hash the two files' bytes; the files the spec
 names (materials, the claims ledger, a scope folder) are not hashed, so "changed" below means the
 draft or the spec. `stations` holds each station's status.
 
@@ -1010,6 +1039,100 @@ the same draft:
 
 A ledger path that leads outside the spec's folder is not written, and `check` prints a warning.
 
+## Sequential works
+
+A course, a primer, a textbook, a book of lessons: a work read in order makes a promise no single
+piece can check. Lesson 5 is written for someone who has read Lessons 1 to 4 and nothing else, so
+every word it uses was defined there. That promise lives across pieces, and it breaks one edit at a
+time: a term moves, a lesson is reordered, a sentence borrows a word from a lesson the reader has
+not reached. Declare the work a sequence and the `sequence` station checks the promise on every run.
+
+### Declaring a sequence
+
+Add `sequence:` to `writing.form`. Every key is optional; this is the course example's, with the
+four that have defaults written out:
+
+```yaml
+    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,
+```
+
+| Key | Default | What it is |
+|---|---|---|
+| `unit` | `Lesson` | the word each unit's heading starts with: `## Lesson 3: Title` |
+| `files` | none | the work's files in reading order, relative to the spec. A `*` in a file name matches within its folder, sorted by number, so `part-2.md` comes before `part-10.md` and a new part is picked up without editing the spec |
+| `sections` | the three shown | what every unit carries, each as a `**Label:**` line or a heading |
+| `terms_section` | `New terms` | the section whose list defines the unit's terms |
+| `outline` | none | an outline whose numbered items promise each unit's terms as `*Terms: a, b.*` |
+| `knows` | none | words a unit may use before a unit defines them, beside `audience.knows` |
+| `teaser` | `Next,` | a closing line starting `**<teaser>` names what is coming; it and everything after it in the unit are exempt from the order guard and the pointer warning |
+
+### How a unit is read
+
+A unit starts at an ATX heading that begins with `unit` and a number, and runs to the next unit
+heading, the next heading of its own level or above, or the end of its file. So a part's own
+heading and introduction belong to no lesson, and neither does a file's YAML frontmatter, which is
+blanked before anything reads the file. A heading inside fenced code is not a heading.
+
+The terms section is its label line and the list under it, to the first blank line after the list.
+Each item defines every bold term before its first `:**`, so `- **Claude Code**, **Codex** and
+**Claude Cowork:** ...` defines three. A term is compared in lower case, with code and emphasis
+marks and any parenthetical dropped. An item that says `(from Lesson 3)` reminds the reader of an
+earlier term and defines nothing.
+
+A use is a whole-word match, ignoring case, where a hyphen joins a word: "context-aware" does not
+use "context", and "skills" does not use "skill". Code is not prose: fenced blocks and inline code
+never count as a use, so `@supersuit/superskill` does not use "supersuit". A unit's own terms
+section is not a use either. Listing a word in `knows` or `audience.knows` is a decision that the
+reader already has it, and it is the only way a unit may use a word before the unit that defines it.
+
+### Checking a sequence
+
+With `files` listed, `check` needs no `--draft`: the files, joined in reading order, are the draft,
+and every station reads them together. A finding names the file and its own line.
+
+```bash
+npx @supersuit/hyperspec check course.hyperspec.md
+```
+
+```
+form: pass
+terms: skip (writing.audience.terms is empty or not set)
+claims: pass
+quotes: pass
+private: pass
+dna: skip (writing.dna.scope_dir is not set)
+links: pass
+sequence: pass
+  warn [station-sequence-forward-pointer] Lesson 1 points forward to Lesson 4 (course/part-1.md line 25)
+    fix: Keep it a pointer ("more in Lesson 4"): Lesson 1 must make sense to a reader who has not read Lesson 4.
+  warn [station-sequence-forward-pointer] Lesson 3 points forward to Lesson 4 (course/part-2.md line 24)
+    fix: Keep it a pointer ("more in Lesson 4"): Lesson 3 must make sense to a reader who has not read Lesson 4.
+verdict: one-shot
+```
+
+`--draft` still works on a sequence spec: it names one file, which may hold every lesson under
+repeated headings. Checked from `files`, `form.length` and `required_parts` apply to the whole work,
+so write `required_parts` as the part headings. A relative link resolves beside the file that holds
+it.
+
+The outline guard checks only the units the draft holds, so a work is checked while it is being
+written: an outline that promises Lessons 1 to 28 checks a draft of Lessons 1 to 20 without
+complaint. A pointer to a later unit is a warning, never a failure: "more in Lesson 12" is fine as
+long as the lesson makes sense without it.
+
+It cannot tell whether a definition is good, whether a term is used in the sense it was defined in,
+or whether a quiz tests what the lessons taught. The judges still take one `--draft` file.
+
 ## Judging a draft
 
 `check` runs the stations that are plain functions of the spec and the draft. The rest of a
@@ -1583,7 +1706,7 @@ not exist.
 
 ## Worked examples
 
-Two complete specs ship in [`examples/writing/`](examples/writing/), each with every file it
+Three complete specs ship in [`examples/writing/`](examples/writing/), each with every file it
 names:
 
 - `essay.hyperspec.md`: an essay for new managers on running a first one-on-one. Three materials
@@ -1592,8 +1715,11 @@ names:
 - `story.hyperspec.md`: a short story, `fiction: true`, narrated by one of its two characters.
   Each character has speech rules, a knowledge timeline by scene, and golden and rejected lines
   in a voice you can tell apart from the other's.
+- `course.hyperspec.md`: a four-lesson course in two part files, declared a sequence (see
+  [Sequential works](#sequential-works)), with an outline promising each lesson's terms. `check`
+  reads the parts with no `--draft` and passes them, with two forward-pointer warnings.
 
-Every material in both is marked. Between them the two examples use all seven labels, each with
+Every material in all three is marked. Between them the essay and the story use all seven labels, each with
 the field it needs, and every spine claim cites the segments that support it. Each segments file
 keeps the boundaries `segments init` wrote, in paragraph mode for prose and sentence mode for
 bulleted notes, so you can re-run it and compare.
@@ -1602,8 +1728,8 @@ Both lint `pass (9/9)` with `writing: 9/9 blocks complete` and no findings. Each
 draft written to it, `essay/draft.md` and `story/draft.md`, with its claims ledger beside it, and
 both drafts pass every station of `check`: the essay with one dna warning, described under
 [dna](#dna), and the story with dna skipped, since it names no scope folder, and quotes skipped,
-since it is fiction. A test lints both
-specs and checks both drafts on every release, so they cannot drift from the tool.
+since it is fiction. The course lints the same way and its parts pass every station. A test
+lints all three specs and checks their drafts on every release, so they cannot drift from the tool.
 
 Each also ships the packets `judge prepare` writes for its draft, in `essay/judge/` and
 `story/judge/`, and one sample verdict per packet in `essay/sample-verdicts/` and
@@ -1615,8 +1741,9 @@ is what `prepare` writes now and records every sample.
 
 ## What later versions add
 
-This release is the schema, its lint, marked materials, scoped DNA, `check` with seven
-deterministic stations, six judgment stations written as packets for an outside judge, and learn.
+This release is the schema, its lint, marked materials, scoped DNA, `check` with eight
+deterministic stations (sequential works among them), six judgment stations written as packets for
+an outside judge, and learn.
 Next: lineups over several passages of one draft, so that one lucky pick carries less weight, and
 a learn step that reads the runs ledger across drafts for the stations that keep failing and the
 changes that made them pass, beside what one pair of drafts shows.

package/bin/hyperspec.mjs

@@ -24,8 +24,10 @@ 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
@@ -358,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);
@@ -389,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;

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.