@supersuit/hyperspec 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # 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

package/README.md

@@ -31,6 +31,10 @@ improvement ledger. Every test is defined in [SPEC.md](SPEC.md).
 | `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
@@ -194,13 +204,15 @@ 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 eight 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
+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) and `sequence` (for a work read in order; see below).
+(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
@@ -219,7 +231,10 @@ it across the whole work: every lesson carries its sections ("After this lesson
 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`:
+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:
@@ -263,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.8.0** (2026-09-29)
+**Version 0.9.0** (2026-09-29)
 
 ## What makes a spec a hyperspec