@supersuit/hyperspec 0.7.0 → 0.9.0

package/WRITING.md

@@ -245,6 +245,11 @@ 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
+      quiz: Check yourself           # optional: the quiz heading; turns on the quiz rules
     check:
       station: structure and length check
     source: form decision
@@ -276,6 +281,14 @@ writing:
       station: every factual claim points at a source span
     source: sourcing pass
     author: agent:claude
+  quotes:                            # optional; not a block, so no check, source or author
+    examples: true                   # true | false | a list of phrasings; see quotes under Checking a draft
+  panel:                             # optional: the panel's readers; the audience's reader joins as buyer
+    - id: skeptic                    # a lower-case slug, unique, never buyer
+      who: a manager who has run one-on-ones for years and doubts that a list is the problem
+      knows:                         # optional
+        - one-on-one
+      lens: what the essay asserts without showing
   characters:                        # required when fiction: true; ids unique
     - id: ines
       entity: world/ines.json        # optional; if given, the file must exist
@@ -337,12 +350,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, or `quiz` empty or a placeholder; `quotes` is present and is not a map, or its `examples` is not `true`, `false` or a list of real phrasings; `panel` is present and is not a list of readers, or a reader has no `id`, `who` or `lens`, an `id` that is not a lower-case slug, an `id` used twice or `buyer`, 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 +823,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 nine 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 +837,8 @@ 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)
+triage: skip (no triage file at essay/triage.jsonl yet; a recorded panel verdict or a triage import starts one)
 verdict: one-shot
 ```
 
@@ -832,10 +847,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.
 
@@ -917,6 +935,22 @@ the station: a character's dialogue is invented rather than quoted from a materi
 `attribution` judge tests it against each character's own lines instead (see
 [Judging a draft](#judging-a-draft)).
 
+A primer shows its reader what to type or say, and "write the update for Dana" in quotation marks
+is an example of a request, not a quotation of anyone. No material holds it, so the station would
+fail it. `writing.quotes.examples` says which quoted spans are examples:
+
+```yaml
+  quotes:
+    examples: true
+```
+
+With `true`, a span whose sentence names no speaker is read as an example and passes unmatched. A
+quotation that names its speaker is still held to the materials, so `Dana said "..."` must still be
+in one of Dana's quote segments. With a list, only the phrasings listed pass, each compared the
+way a span is matched, and every other span is checked as before. The list is the stricter
+choice: under `true`, a made-up quotation that names no one passes too. `false`, or no `quotes`
+key, checks every span.
+
 | Id | Severity | Meaning |
 |---|---|---|
 | `station-quotes-unmatched` | fail | a quoted span is in no quote or story segment |
@@ -973,6 +1007,53 @@ 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, each lesson defines what the outline promises, and, when the
+spec names a quiz heading, the quizzes test every term in order. How a unit and a quiz are 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 |
+| `station-sequence-quiz-missing` | fail | `quiz` is set and the draft has no quiz heading |
+| `station-sequence-quiz-untagged` | fail | a numbered line in a quiz names no unit it tests |
+| `station-sequence-quiz-answer` | fail | a question has no answer on its quiz's answers line, or its answer is not one of its options |
+| `station-sequence-quiz-used-before-defined` | fail | a question uses a term a later unit than its tagged one defines; points at the question |
+| `station-sequence-quiz-untested` | fail | no question uses a defined term, or its simple plural; points at the defining unit |
+
+### triage
+
+Runs when the spec's triage file exists (`triage.jsonl`, beside the runs ledger), and holds every
+finding in it to its answer: a finding nobody answered fails, a `taken` or `already-true` answer
+fails unless the passage it quotes is in the draft as it is now, and a `kept` answer fails without
+its reason. An `open` finding is a warning, since it is a decision for the operator and the draft
+can ship while it waits. So is a `kept` or `open` answer about a passage that has since left the
+draft. How findings arrive and how they are answered are under [Triage](#triage-1). With no triage
+file the station skips. It checks that an answer's evidence is in the draft, never whether the
+passage does what the finding asked.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-triage-unreadable` | fail | a line of the triage file is not a finding: not JSON, or no `finding_id` or `text` |
+| `station-triage-untriaged` | fail | a finding has no disposition; names it, at its evidence's line |
+| `station-triage-disposition` | fail | a finding's disposition is not `taken`, `kept`, `already-true` or `open` |
+| `station-triage-evidence-missing` | fail | a `taken` or `already-true` answer quotes no passage of at least three words |
+| `station-triage-evidence-not-found` | fail | a `taken` or `already-true` answer quotes a passage that is not in the draft |
+| `station-triage-reason-missing` | fail | a `kept` answer gives no reason |
+| `station-triage-open` | warn | a finding is open, a decision still to make |
+| `station-triage-stale` | warn | a `kept` or `open` answer is about a passage that is no longer in the draft |
+
 ### Any station
 
 | Id | Severity | Meaning |
@@ -985,11 +1066,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","triage":"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 +1093,131 @@ 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,
+      quiz: Check yourself
+```
+
+| 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 |
+| `quiz` | none | the heading each quiz starts with; set, it turns on the quiz rules (see How a quiz is read) |
+
+### 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.
+
+### How a quiz is read
+
+With `quiz` set, the station also holds the work's quizzes to the promise a quiz makes: it tests
+what the lessons taught, and only what the reader has been taught by the lesson it names. A quiz
+starts at a heading that begins with `quiz`, in any case, and runs to the next heading of its level
+or above or the end of its file, so a quiz between two lessons belongs to neither. These are the
+first two questions of the course example's first quiz, under its heading `## Check yourself: Part 1`:
+
+```markdown
+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
+```
+
+A question is a numbered line tagged `*(<unit> N)*`, the unit it tests. It runs to the next
+numbered line, and its options are the indented `- a) ` lines inside it. A quiz ends with one
+`**Answers:**` line of number and letter pairs, `**Answers:** 1 b · 2 a`, in any separator. Every
+term a unit defines must be used by some question, where a simple plural counts ("doughs" tests
+"dough"); no question, options included, may use a term a later unit defines than the one it is
+tagged with, except a word in `knows`; every numbered line in a quiz must carry a tag; and every
+question's answer must name one of its options. Code in a question is not a use, as in a lesson.
+The rules and the question shape are those of the checker the first book written this way used,
+promoted here so every sequential work gets them.
+
+### 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.
+triage: skip (no triage file at course/triage.jsonl yet; a recorded panel verdict or a triage import starts one)
+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 question that uses a term tests understanding of it rather than only naming it. 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
@@ -1033,6 +1241,10 @@ essay/judge/lineup.packet.json
 essay/judge/lineup.key.json
 essay/judge/reader.packet.json
 essay/judge/persona.packet.json
+essay/judge/panel-skeptic.packet.json
+essay/judge/panel-novice.packet.json
+essay/judge/panel-expert.packet.json
+essay/judge/panel-buyer.packet.json
 attribution: skip (the spec is not fiction; attribution applies only with fiction: true)
 knowledge: skip (the spec is not fiction; knowledge applies only with fiction: true)
 ```
@@ -1040,8 +1252,9 @@ knowledge: skip (the spec is not fiction; knowledge applies only with fiction: t
 Like `check`, it lints the spec first: a spec that fails lint, or is blocked on an open
 decision, gets no packet, and `prepare` exits with lint's own code. Then it writes one
 `<station>.packet.json` for each station that applies, in a fixed order (`doctor, lineup,
-reader, persona, attribution, knowledge`), and prints a `skip` line with the reason for each
-that does not. `--only doctor,reader` prepares just those. The `--out` folder must already
+reader, persona, attribution, knowledge, panel`), and prints a `skip` line with the reason for each
+that does not. The panel writes one packet per reader, `panel-<reader>.packet.json`. `--only
+doctor,reader` prepares just those. The `--out` folder must already
 exist. `prepare` refuses to overwrite any file it would write, naming every one, and then writes
 nothing; `--force` replaces them. The worked examples ship the packets this writes, so add
 `--force` to write them again there. The same spec and draft, with the same goldens and claims
@@ -1096,7 +1309,8 @@ it cannot find the spec and exits 2.
 ### The evidence rule
 
 Every verdict field that cites the draft (the doctor's `evidence`, the reader's `lost_at` and
-`stopped_at`, the persona's `breaks`, the knowledge `leaks`) is a span copied from the draft. A
+`stopped_at`, the persona's `breaks`, the knowledge `leaks`, every panel item) is a span copied
+from the draft. A
 span counts only when:
 
 - it has at least three words, where a word is a run of letters and digits (so "It's" is two);
@@ -1329,6 +1543,59 @@ them by order. Write `by` as something a reader of the draft can find.
 | `judge-knowledge-leak` | fail | a character knows something too early, at its evidence's line |
 | `judge-knowledge-character-unknown` | invalid | a leak names a character with no timeline in the packet |
 
+### panel
+
+The draft read by several readers at once, each through their own lens: the pressure test a
+draft gets by hand before it ships, made part of the run. Every other station asks one question
+with a right answer; the panel asks each reader what works, what to improve, what is missing and
+what to remove, and each thing they would change is a finding somebody has to answer (see
+[Triage](#triage-1)). Applies when `writing.audience` is written and its check has a rubric, the
+reader station's own condition, because one of the readers is always the audience's own.
+
+The readers are the ones `writing.panel` lists, each with an `id`, `who`, what they already `knows`
+and the `lens` they read for:
+
+```yaml
+  panel:
+    - id: skeptic
+      who: a manager who has run one-on-ones for years and doubts that a list is the problem
+      lens: what the essay asserts without showing
+```
+
+With no `panel` declared, three readers read it: a `skeptic`, who doubts the central claim and
+reads for what is asserted without support; a `novice`, new to the subject, reading for every
+term, step or assumption left unexplained; and an `expert` in the subject, reading for what is
+wrong, out of date or oversimplified. Declared or not, the audience's own reader joins last as
+`buyer`, built from `audience.who`, `audience.knows` and `audience.wants`: a panel that never
+includes the person the piece is for tests everything except whether it works for them.
+
+There is one packet per reader. Inputs: `reader` (`id`, `who`, `knows`, `lens`) and the `draft`;
+the rubric is the audience block's. The verdict is `{ good, improve, missing, remove }`, four
+lists, any of them empty, where every item is `{ evidence, note }`: a span copied from the draft,
+and what and why in a sentence. A missing item quotes the passage nearest where the missing thing
+belongs. The panel never fails a draft. Each improve, missing and remove item is a warning at its
+evidence's line, and goes to the spec's triage file as a finding to answer; what works is counted
+and never triaged, since there is nothing to answer. The summary line counts all four and the
+findings added:
+
+```
+panel: pass
+  skeptic: 1 good, 1 to improve, 0 missing, 0 to remove; 1 added to triage (story/triage.jsonl)
+  warn [judge-panel-improve] skeptic would improve this: The red ring is planted hard; a doubting reader sees the sale coming a scene before Ines says it. (line 63)
+    fix: Answer it in the triage file: take it, keep the passage with a reason, show it is already true, or leave it open for a decision.
+verdict: one-shot
+```
+
+Each reader has its own history in the runs ledger: a panel judge line carries `reader` after
+`station`, and is compared only with that reader's earlier lines. Recording the same verdict twice
+adds nothing to triage, since a finding's id is a hash of what it says.
+
+| Id | Kind | Meaning |
+|---|---|---|
+| `judge-panel-improve` | warn | the reader would change this passage, and why |
+| `judge-panel-missing` | warn | the reader needs something the draft does not give, near this passage |
+| `judge-panel-remove` | warn | the reader would cut this passage, and why |
+
 ### Any judgment station
 
 | Id | Kind | Meaning |
@@ -1399,10 +1666,181 @@ copy on every release.
 | story | persona | fail | three process details (the deck oven's heat-up time, the rolls' bake time, how the starter is fed) are in no claim, and the rubric allows none outside the ledger |
 | story | attribution | pass | all 19 lines named right by voice alone |
 | story | knowledge | pass | neither character knows anything early |
+| essay | panel-skeptic | pass | the claim rests on a count; "three is enough" is asserted, and who answered the survey is never said |
+| essay | panel-novice | pass | the one term a newcomer lacks is defined where it appears; the running agenda needs a first step |
+| essay | panel-expert | pass | the follow-through is right; say what to do when the silence runs on, and cut the opening disaster story |
+| essay | panel-buyer | pass | it ends on the card; it misses what to do when the report says nothing, at the same passage as the expert |
+| story | panel-skeptic | pass | the letter is carried by what Theo does not do; the red ring round Friday gives the sale away |
+| story | panel-novice | pass | the deck oven is shown where it is named; the proving cabinet is not |
+| story | panel-expert | pass | the flour is weighed, as in a real bakery; the starter is never shown being fed |
+| story | panel-buyer | pass | the first line of Ines's speech holds the reader; the red ring again, and a radio that goes nowhere |
 
 Both examples pass every station of `check`. Each failure here is something no deterministic
 station can see.
 
+## Triage
+
+A panel verdict, or an outside review, is a list of findings, and a finding is only useful once
+someone has decided what to do about it. Triage is where that happens: every finding lands in one
+file, each gets one of four answers, `check` holds every answer to the draft as it is now, and a
+reply to the reviewer is written from the answers. Four answers, because a finding ends in one of
+four places:
+
+| Disposition | Means | Needs |
+|---|---|---|
+| `taken` | the draft now does what the finding asked | `--evidence`: the passage of the current draft that does it |
+| `kept` | the passage stays as it is, on purpose | `--reason`: why |
+| `already-true` | the draft already did it | `--evidence`: the passage that does it |
+| `open` | a decision for the operator | `--reason`, optionally: what is to decide |
+
+Evidence follows [the evidence rule](#the-evidence-rule) a judge's quotes follow, against the
+draft as it is when the answer is given. Nothing in triage reads meaning: it holds an answer's
+evidence to the draft word for word, and the person answering decides whether the passage does
+what the finding asked.
+
+### The triage file
+
+Findings live in `triage.jsonl` beside the spec's runs ledger (`improvement.ledger`), so the
+story example's is `story/triage.jsonl`. Recording a panel verdict adds the reader's improve,
+missing and remove items to it, and `triage import` adds an outside review's. Each line is one
+finding:
+
+```json
+{"finding_id":"panel-skeptic-aeb09835","source":"panel","reader":"skeptic","kind":"improve","text":"The red ring is planted hard; a doubting reader sees the sale coming a scene before Ines says it.","evidence":"somebody had drawn a ring round Friday in red pen","draft_sha256":"fdf8dd1ee311a376e45cca31b50f0b01f1157a889cb332620cbd178e9c510306","disposition":null,"answer":null}
+```
+
+`finding_id` is `panel-<reader>-` or `import-` and eight characters of a hash of what the finding
+says, so the same finding recorded twice is one finding. `source` is `panel` or where an imported
+review came from, `reader` the panel reader or the review's heading, `kind` one of `improve`,
+`missing` and `remove`, or `note` for an imported point under no such label. `evidence` is the
+passage the finding is about, and `draft_sha256` the draft it was raised against. `disposition` and
+`answer` are null until the finding is answered; then `answer` holds `evidence` or `reason` as
+given, the draft's `draft_sha256` and the time, `at`.
+
+### Answering a finding
+
+Record the four panel samples of the story (see [panel](#panel)), then answer each finding:
+
+```bash
+npx @supersuit/hyperspec triage answer story.hyperspec.md panel-novice-47ce4719 already-true --draft story/draft.md --evidence "Ines will not put it in the proving cabinet. She says the cabinet is for the white."
+npx @supersuit/hyperspec triage answer story.hyperspec.md panel-buyer-23aee52f kept --draft story/draft.md --reason "the radio nobody turns on is the silence the bench scene depends on"
+npx @supersuit/hyperspec triage answer story.hyperspec.md panel-expert-ef15b7b2 kept --draft story/draft.md --reason "the starter is the one thing Theo is never allowed to touch, so he never sees it fed"
+npx @supersuit/hyperspec triage answer story.hyperspec.md panel-skeptic-aeb09835 open --draft story/draft.md --reason "how early to plant the sale is the author's call"
+npx @supersuit/hyperspec triage answer story.hyperspec.md panel-buyer-57810b16 open --draft story/draft.md --reason "the same call as the skeptic's"
+npx @supersuit/hyperspec triage status story.hyperspec.md --draft story/draft.md
+```
+
+Each answer prints `<finding>: <disposition> (story/triage.jsonl)`. `status` counts the answers,
+lists the passages two or more readers raised findings about, and runs the triage station's rules:
+
+```
+story/triage.jsonl: 5 findings; 0 taken, 2 kept, 1 already true, 2 open, 0 not answered
+shared by two or more readers:
+  line 63: "somebody had drawn a ring round Friday in red pen"
+    skeptic (improve): The red ring is planted hard; a doubting reader sees the sale coming a scene before Ines says it.
+    buyer (improve): I guessed Friday before the reveal, which took some of the weight out of the oven scene.
+triage: pass
+  warn [station-triage-open] panel-skeptic-aeb09835 (skeptic, improve) is open: "The red ring is planted hard; a doubting reader sees the sale coming a scene be…" (how early to plant the sale is the author's call) (line 63)
+    fix: A decision for the operator; answer it once it is made.
+  warn [station-triage-open] panel-buyer-57810b16 (buyer, improve) is open: "I guessed Friday before the reveal, which took some of the weight out of the ov…" (the same call as the skeptic's) (line 63)
+    fix: A decision for the operator; answer it once it is made.
+```
+
+The shared passages are the synthesis of a panel: where two or more readers point at overlapping
+passages of the draft, the passage is worth reading first. It groups by where, never by meaning,
+so two readers who say the same thing about different passages are not grouped.
+
+`answer` refuses, and writes nothing, when a `taken` or `already-true` answer's evidence is missing,
+under three words or not in the draft, or a `kept` answer has no reason. It may be given again: the
+last answer stands. Like `check`, every triage command takes `--draft`, or reads the files of a
+spec that lists `writing.form.sequence.files`, and names a finding's line by the file that holds
+it.
+
+### Importing an outside review
+
+A review written anywhere else, as markdown or plain text, comes in as findings with `triage
+import`, so it gets the same answers and the same check as the panel. This is a short review of the
+story:
+
+```markdown
+#### The magazine's editor
+
+**Good:** the opening puts the reader in the kitchen at once.
+
+**Improve:**
+
+- The oven noise comes twice; the second, "It made the noise while I was weighing the second batch", could go.
+
+**Missing:**
+
+- Theo never says what he wants: "I did not look at the coat. I looked at the dough." carries it, but only just.
+
+#### A first-time reader
+
+- Remove: the line about "the bakery closing on a Tuesday" felt out of place.
+```
+
+```bash
+npx @supersuit/hyperspec triage import story.hyperspec.md story/review.md --draft story/draft.md --source "the editor's review"
+```
+
+```
+the editor's review: 3 findings added to triage (story/triage.jsonl); 1 item of praise, not triaged
+  warn [triage-import-quote-not-found] a finding quotes text that is not in the current draft: "the bakery closing on a Tuesday" (the line about "the bakery closing on a Tuesday" felt out o…)
+    fix: The review may have read another copy of the draft. Check the finding against the draft as it is now before answering it.
+```
+
+A heading names the reader of the points under it. A label (`Good`, `Improve`, `Improvement`,
+`Missing` or `Remove`, as a heading, a bold line, or a word and a colon starting a line or a list
+item) sets the kind of what follows. Each list item, with its indented lines, is one finding, and
+so is a paragraph under a label; an introduction under no label is not. What is good is counted
+and left out, since there is nothing to answer. A finding's evidence is the first quoted span, in
+double quotation marks or a `>` quotation block, of three words or more that is in the draft. A
+finding that quotes only text the draft does not hold is imported with no evidence and a warning:
+a review of a stale or partial copy is the usual cause, and the finding is still answered.
+`--source` names the review, by default its file's path, so a reply can be written to it alone.
+
+### Replying to the reviewer
+
+```bash
+npx @supersuit/hyperspec triage answer story.hyperspec.md import-6c60f92a kept --draft story/draft.md --reason "the second time is when Theo starts to listen to it"
+npx @supersuit/hyperspec triage answer story.hyperspec.md import-919ea916 already-true --draft story/draft.md --evidence "I did not look at the coat. I looked at the dough."
+npx @supersuit/hyperspec triage answer story.hyperspec.md import-ad3d7fe9 kept --draft story/draft.md --reason "no line about a Tuesday closing is in the draft; the review read another copy"
+npx @supersuit/hyperspec triage reply story.hyperspec.md --draft story/draft.md --source "the editor's review"
+```
+
+```
+Thank you for the review. Here is what happened to each point.
+
+Kept as it is:
+- The magazine's editor: The oven noise comes twice; the second, "It made the noise while I was weighing the second batch", could go. Why: the second time is when Theo starts to listen to it
+- A first-time reader: the line about "the bakery closing on a Tuesday" felt out of place. Why: no line about a Tuesday closing is in the draft; the review read another copy
+
+Already in the draft:
+- The magazine's editor: Theo never says what he wants: "I did not look at the coat. I looked at the dough." carries it, but only just. It is here: "I did not look at the coat. I looked at the dough."
+```
+
+`reply` prints plain text, one line per finding, under Taken, Kept as it is, Already in the draft
+and Still open, leaving out an empty heading, and anything not answered yet under a last heading
+of its own. It never sends anything: it is a draft for the operator to read and send, or not. It
+exits 1, with a line on stderr, when the triage station would fail, so a reply with a gap in it is
+not sent by accident. `--source` limits it to one review; without it every finding is included.
+
+Exit codes: `status` **0** when the triage station would pass, **1** when it would fail; `answer`
+**0** written, **1** refused; `import` **0** imported, **1** the review holds no finding; `reply`
+**0** ready, **1** not; all four **2** on usage: no spec, a spec without `profile: writing`, no
+draft, no triage file for `answer` and `reply`, an unknown finding or disposition, or a review that
+cannot be read. `--json` prints the whole result.
+
+| Id | Kind | Meaning |
+|---|---|---|
+| `triage-evidence-missing` | invalid | a `taken` or `already-true` answer has no `--evidence` |
+| `triage-evidence-too-short` | invalid | the answer's evidence has fewer than three words |
+| `triage-evidence-not-found` | invalid | the answer's evidence is not in the draft |
+| `triage-reason-missing` | invalid | a `kept` answer has no `--reason` |
+| `triage-import-quote-not-found` | warn | an imported finding quotes text, and none of it is in the draft |
+| `triage-import-empty` | invalid | the review holds no finding to answer |
+
 ## Learning from edits
 
 A factory writes a first draft, and a person edits it into the draft they approve. Every edit is
@@ -1583,7 +2021,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 +2030,12 @@ 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 and a
+  quiz closing each part. `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,21 +2044,24 @@ 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
-`story/sample-verdicts/`, filled in by hand and marked as samples; what each found is under
-[The worked examples](#the-worked-examples). The essay adds a learn pair in `essay/learn/`: a
+`story/sample-verdicts/`, filled in by hand and marked as samples, four panel readers' among
+them; what each found is under [The worked examples](#the-worked-examples), and the story's panel
+findings are triaged under [Triage](#triage-1). The essay adds a learn pair in `essay/learn/`: a
 first draft, the packet `learn prepare` writes comparing it with `essay/draft.md`, and a sample
 learn verdict (see [Learning from edits](#learning-from-edits)). A test checks that every packet
 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 nine
+deterministic stations (sequential works and their quizzes among them, and triage last), seven
+judgment stations written as packets for an outside judge (the panel among them), triage, 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.