@supersuit/hyperspec 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 0.9.0 (2026-09-29)
+
+The pressure test a draft gets before it ships is now part of the run, and so is answering it.
+Several readers reading a draft through their own lenses, and someone deciding what to do about
+each thing they said, was done by hand twice, once for a letter and once for a book outline, and
+both times the review read a stale, truncated copy and none of its readers was the person the
+piece was for. The `panel` judge fixes both by construction, and `hyperspec triage` holds every
+finding, the panel's or an outside review's, to an answer that `check` keeps true against the draft.
+
+- The `panel` judgment station, the seventh, run last. One packet per reader,
+  `panel-<reader>.packet.json`: the readers the new optional `writing.panel` lists (`id`, `who`,
+  `knows`, `lens`), or by default a `skeptic`, a `novice` and an `expert`, and always the audience's
+  own reader, added last as `buyer`. It applies when the reader station does (a written audience
+  with a rubric). The verdict is `{ good, improve, missing, remove }`, every item `{ evidence, note }`
+  under the evidence rule, so a review of any copy but the current draft is refused. The panel
+  never fails a draft: improve, missing and remove items are warnings (`judge-panel-improve`,
+  `-missing`, `-remove`) and go to the triage file. A panel ledger line carries `reader`, and each
+  reader's history is its own. Lint refuses a panel that is not a list of readers, a reader with no
+  id, who or lens, an id that is not a slug, used twice or `buyer`, and a hollow `knows`
+  (`writing-panel`, `-reader`, `-id`, `-id-duplicate`, `-buyer`, `-who`, `-lens`, `-knows`, test 1).
+- `triage.jsonl`, beside the runs ledger: one finding per line, `{ finding_id, source, reader, kind,
+  text, evidence, draft_sha256, disposition, answer }`, each once (the id hashes what it says).
+- The `triage` station, run last in `check`: fails on an unanswered finding
+  (`station-triage-untriaged`), a `taken` or `already-true` answer whose evidence is missing or not
+  in the draft (`-evidence-missing`, `-evidence-not-found`), a `kept` answer with no reason
+  (`-reason-missing`), a disposition outside the four (`-disposition`) or a line that is not a
+  finding (`-unreadable`); warns on an `open` finding (`-open`) and on a kept or open answer about a
+  passage that has left the draft (`-stale`). With no triage file it skips.
+- `hyperspec triage status` (the counts, the station's rules, and the synthesis: every passage two
+  or more readers raised findings about), `triage answer` (refuses with `triage-evidence-missing`,
+  `-too-short`, `-not-found` or `triage-reason-missing`, writing nothing), `triage import` (an
+  outside review in markdown or plain text as findings: headings name readers, Good, Improve,
+  Missing and Remove labels set the kind, praise is counted and not triaged, and a quote the draft
+  does not hold warns, `triage-import-quote-not-found`; `triage-import-empty` when there is nothing
+  to answer) and `triage reply` (a plain-text reply to the reviewer; it never sends, and exits 1
+  while a finding is unanswered).
+- The quotes station reads the new optional `writing.quotes.examples`: `true` reads a quoted span
+  whose sentence names no known speaker as an example phrasing, not a quotation; a list exempts
+  exactly those phrasings. A quotation that names its speaker is checked either way. Lint refuses
+  any other value (`writing-quotes`, `writing-quotes-examples`, test 1).
+- The sequence station gains the quiz rules, on when the new `writing.form.sequence.quiz` names the
+  quiz heading: every defined term tested by some question (a simple plural counts), no question
+  using a term defined after the unit it is tagged with, every question tagged, every answer one of
+  its options (`station-sequence-quiz-missing`, `-untagged`, `-answer`, `-used-before-defined`,
+  `-untested`). Promoted from the checker the first book written this way used, with its question
+  shape. A hollow `quiz` fails lint (`writing-form-sequence-quiz`, test 1).
+- The evidence rule moved to `src/evidence.mjs`, shared by `judge record` and `triage`; `judge.mjs`
+  re-exports what it exported.
+- The worked examples: the essay and the story ship four panel packets each, with a hand-filled
+  sample verdict per reader; the course carries a quiz at the end of each part and `quiz: Check
+  yourself`.
+
+**Behavior change:** `check` runs nine stations, so `--json` and the ledger's `stations` carry
+`triage` (as `skip` for every spec without a triage file). `judge prepare` writes the four panel
+packets for every spec whose audience has a rubric, where 0.8 wrote none; `--only` still limits it.
+No other finding id changed.
+
+## 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,9 +28,13 @@ 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 triage status <spec> [--draft <file>]` | Count every finding's answer, list the passages two or more readers share, and hold every answer to the draft. |
+| `hyperspec triage answer <spec> <finding> taken\|kept\|already-true\|open [--evidence S] [--reason S] [--draft <file>]` | Answer one finding: evidence from the draft for taken and already-true, a reason for kept. |
+| `hyperspec triage import <spec> <review> [--source S] [--draft <file>]` | Bring an outside review in as findings to answer. |
+| `hyperspec triage reply <spec> [--source S] [--draft <file>]` | Print a plain-text reply to the reviewer from the answers. Never sends anything. |
 | `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. |
 | `hyperspec learn record <packet> --verdict <file>` | Count the classified edits by block and name one next move. |
 | `hyperspec recipe check <output-or-recipe>` | Check that a recipe records everything the standard asks for. |
@@ -57,6 +61,12 @@ and 1 when it refused. `judge prepare` and `learn prepare` exit 0 when they wrot
 with lint's own code when the spec is not ready, and `judge prepare` exits 1 when a station could
 not build its packet. All four exit 2 on a usage error.
 
+`hyperspec triage status` exits 0 when every finding is answered and every answer holds against
+the draft, and 1 when not; `triage answer` 0 when it wrote the answer and 1 when it refused it;
+`triage import` 0 when it imported and 1 when the review holds nothing to answer; `triage reply` 0
+when the reply is ready to send and 1 when a finding is still unanswered. All four exit 2 on a
+usage error.
+
 The recipe commands use the same numbers: 0 ok, 1 a check failed or the child regressed, 2
 usage or unreadable input, 3 pending, when `regenerate` has stages waiting for a runner.
 `regenerate` also exits 1 when a stage it ran reported a failing verdict, or none. A stage it
@@ -145,9 +155,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 +204,53 @@ 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 nine 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).
+words or more is word for word in a marked quote; `writing.quotes.examples` marks example
+phrasings such as "write the update for Dana" as examples rather than quotations), `private` (no run of eight words from a
+private segment), `dna` (the draft's measured style beside its scope's, as warnings), `links`
+(well-formed, and relative links resolve), `sequence` (for a work read in order; see below) and
+`triage` (every reader's finding answered, and every answer held to the draft; 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. Name the quiz heading as `quiz:` and every quiz is held to it too: every
+defined term tested by some question, no question using a term from a lesson after the one it is
+tagged with, and every answer one of its question's options. 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
@@ -237,6 +278,32 @@ style rule". It never edits the spec. Both examples ship their packets and hand-
 verdicts. The packet shapes, every station's rules and findings, and the learn tally are in
 [WRITING.md](WRITING.md#judging-a-draft).
 
+### A reader panel, and answering what it found
+
+A draft gets pressure-tested before it ships: several readers read it, each through their own
+lens, and say what works, what to improve, what is missing and what to remove. The `panel` judge
+makes that part of the run. It writes one packet per reader, the ones `writing.panel` lists or by
+default a skeptic, a newcomer and an expert, and always the audience's own reader as `buyer`,
+since a panel that never includes the person the piece is for tests everything but that. Every
+item a reader lists quotes the draft word for word, so a review of a stale copy is refused.
+
+Each thing a reader would change becomes a finding in `triage.jsonl`, beside the runs ledger, and
+so does each point of an outside review brought in with `triage import`. Every finding gets one
+answer: `taken` (with the passage of the draft that now does it), `kept` (with the reason),
+`already-true` (with the passage that already did it) or `open` (a decision for you). `check` fails
+while a finding is unanswered or an answer's passage is no longer in the draft, and warns on an
+open one. `triage reply` turns the answers into a plain-text reply to the reviewer, for you to send.
+
+```bash
+npx @supersuit/hyperspec judge record story/judge/panel-skeptic.packet.json --verdict story/sample-verdicts/panel-skeptic.verdict.json
+npx @supersuit/hyperspec triage status story.hyperspec.md --draft story/draft.md
+npx @supersuit/hyperspec triage answer story.hyperspec.md panel-skeptic-aeb09835 open --draft story/draft.md --reason "the author's call"
+npx @supersuit/hyperspec triage reply story.hyperspec.md --draft story/draft.md
+```
+
+The triage file, every answer's rule, how a review is read, and every finding are in
+[WRITING.md](WRITING.md#triage-1).
+
 ## The format
 
 A hyperspec is a markdown file with a YAML frontmatter block: `decisions`, `requirements`,

package/SPEC.md

@@ -97,7 +97,7 @@ examples:
   - path: examples/minimal.hyperspec.md
     why: the smallest spec that passes all nine tests
 resume:
-  next_action: collect adopter issues on 0.7, the judge and learn commands included, and cut 0.8 from them
+  next_action: collect adopter issues on 0.9, the panel and triage included, and cut 0.10 from them
 feedback:
   issues: https://github.com/SupersuitUp/hyperspec/issues
   fork: MIT; fork it for your own purposes and say so in your SPEC
@@ -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.9.0** (2026-09-29)
 
 ## What makes a spec a hyperspec