@supersuit/hyperspec 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.10.0 (2026-10-02)
+
+What a drafting loop and a per-audience renderer need to run on the engine without hand work
+(build 7 wiring, from the letter's BUILD-NOTES).
+
+- **A draft's frontmatter and HTML comments are not prose.** `check`, `judge` and `learn` read every
+  draft through `readDraft`, which now blanks a leading YAML frontmatter block and every
+  `<!-- ... -->` comment line for line (their characters go, their line breaks stay, so line
+  numbers are the file's own). A kept document (a title, a status, a note to self about what it
+  was meant to be) grades exactly as its prose does. Sequence drafts already blanked frontmatter;
+  they now blank comments too. `hideUnseen` in `src/draft.mjs` is the rule.
+- **`hyperspec segments label <segments-file> <ids>=<label>[:key=value]...`** labels segments in
+  place: `s1,s4=aside`, `s3=quote:speaker=gary-sheng`, `s2=claim:own=true` (`own=true` is written as
+  the boolean). Offsets and text never change. An unknown id, a label outside the closed set or a
+  malformed assignment exits 2 with nothing written. It prints what is still unlabeled.
+  `labelSegments` and `parseLabelAssignment` in `src/segments.mjs`.
+- **`hyperspec ready <spec> [--draft <file>] [--judges a,b] [--json]`** answers whether this draft
+  has been through the engine under this spec, from the runs ledger alone: the latest full check
+  of these exact draft and spec bytes passed; every required judge (the list given, or every judge
+  that applies) passed on the same bytes, each panel reader including the buyer; and that check
+  came after the last of those judge lines, so the panel's findings were triaged and held. Exit 0
+  ready, 1 not ready with each missing step listed, 2 usage.
+- **`specText(data, body)` and `parseSpecText(text)`**, exported from `@supersuit/hyperspec/writing`, writes a spec's text
+  from data and reads it back with the linter's own reader, throwing (and naming the field) when
+  any value would not come back unchanged. For tools that build specs rather than people typing
+  them.
+
+**Behavior change:** a draft whose frontmatter or comments held words now counts fewer words, and a
+term that first appeared in a comment now first appears in the prose. No finding id changed.
+
+## 0.9.1 (2026-09-30)
+
+Two fixes, each found by the first book written as a sequence.
+
+- The sequence station no longer reads a word inside a longer defined term as a use of the shorter
+  one. A book that defines "Thinking level" in Lesson 2 and "Level" in Lesson 22 failed
+  `station-sequence-used-before-defined` and `station-sequence-quiz-used-before-defined` at every
+  "thinking level" before Lesson 22. Before it looks for a term, the station now blanks every other
+  defined term that contains it as a whole-word phrase, a trailing plural "s" included, in the order
+  guard, the quiz order guard and quiz coverage. The shorter term on its own still counts, and the
+  longer term no longer tests the shorter one in a quiz. `longerTerms` and `maskLonger` are exported
+  from the station.
+- `hyperspec segments init <material> --id <mid> --keep <old>` re-marks an edited material without
+  relabeling what did not change (issue #2). Every segment whose text, trimmed, a segment in `<old>`
+  has keeps that segment's id, label and every other key (`own`, `source`, `teller`, `speaker`, and
+  anything added by hand), with new offsets; the rest start `unlabeled` with the next unused
+  `s<n>` id, and the command lists them. The id is carried so the spine's citations keep pointing
+  at the same words. `--keep` may name the file being written, so a material is re-marked in place;
+  otherwise an existing file is still never overwritten. It exits 2 for a `--keep` file that cannot
+  be read, has a line that is not a JSON object, or marks another material. `carrySegments` in
+  `src/segments.mjs` is the logic.
+
+**Behavior change:** a sequential work that defines a term inside a longer one may now pass where
+0.9.0 failed it, and a quiz whose only question on a shorter term used it inside the longer term now
+fails `station-sequence-quiz-untested` for that term. No finding id changed.
+
 ## 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.

package/README.md

@@ -25,10 +25,12 @@ improvement ledger. Every test is defined in [SPEC.md](SPEC.md).
 | `hyperspec lint <file...> [--json]` | Score each hyperspec against the nine tests. |
 | `hyperspec init <file> [--title T] [--kind K]` | Write a new hyperspec skeleton. Refuses to overwrite an existing file. |
 | `hyperspec init <file> --profile writing [--title T] [--form F] [--fiction]` | Write a writing-spec skeleton, every block shown with placeholders. |
-| `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 segments init <material> --id <mid> [--out F] [--by paragraph\|sentence] [--keep OLD]` | Split a material into segments to label. With `--keep`, re-mark an edited material: every segment whose text is unchanged keeps its id and labels, and only the rest are listed to label. Refuses to overwrite an existing file unless `--keep` names it. |
+| `hyperspec segments label <segments-file> <ids>=<label>[:key=value]...` | Label segments in place (`s1,s4=aside`, `s3=quote:speaker=gary-sheng`, `s2=claim:own=true`); offsets and text never change. Refuses an unknown id or label with nothing written. |
 | `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, or, for a sequential work, against its files in reading order. |
+| `hyperspec ready <spec> --draft <file> [--judges a,b]` | Has this draft been through the engine? From the runs ledger only: a passing full check of these exact bytes, every required judge passing on them (each panel reader, the buyer included), and the check after the last judge so triage was held. Exit 0 ready, 1 not ready with each missing step listed. |
 | `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. |
@@ -43,7 +45,7 @@ improvement ledger. Every test is defined in [SPEC.md](SPEC.md).
 | `hyperspec regenerate <recipe> --out <path> --clicker <slug> <one change> [--run cmd]` | Make a child recipe from a parent and one named change, rerunning only the stages it reaches. |
 | `hyperspec compare <child-recipe> --doctor cmd` | Grade a child and its parent through one doctor against one spec. |
 
-Every command except `init`, `segments init` and `dna init` takes `--json`. `hyperspec --help` prints every flag.
+Every command except `init`, `segments init`, `segments label` and `dna init` takes `--json`. `hyperspec --help` prints every flag.
 
 ## Exit codes
 

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.9.0** (2026-09-29)
+**Version 0.10.0** (2026-10-02)
 
 ## What makes a spec a hyperspec
 

package/WRITING.md

@@ -397,17 +397,21 @@ writing spec cannot pass until every material it draws on is marked.
 npx @supersuit/hyperspec segments init materials/voice-memo.md --id voice-memo
 ```
 
-`hyperspec segments init <material> --id <mid> [--out <file>] [--by paragraph|sentence]` writes
-`<material>.segments.jsonl`, or the path `--out` names. `--by paragraph`, the default, makes one
+`hyperspec segments init <material> --id <mid> [--out <file>] [--by paragraph|sentence] [--keep <old>]`
+writes `<material>.segments.jsonl`, or the path `--out` names. `--by paragraph`, the default, makes one
 segment per paragraph. `--by sentence` makes one per sentence, and a new line that opens on a list
 marker (`-`, `*`, `+`, `1.` or `1)`, then a space) also starts a segment, so each bullet in a set
 of notes stands on its own. Every segment starts as `unlabeled`, which lint never accepts. `init`
-refuses to overwrite a file that exists, and exits 2 on a material that does not exist or a
-`--by` it does not know, a material with nothing in it, and an `--out` folder that does not
-exist.
+refuses to overwrite a file that exists, unless `--keep` names that file (see
+[When a material changes](#when-a-material-changes)), and exits 2 on a material that does not
+exist or a `--by` it does not know, a material with nothing in it, and an `--out` folder that does
+not exist.
 
 Then name the file on the material item, as `segments:` beside `path:`, and label every segment.
-You may also move a boundary by hand, splitting one segment in two or joining two, as long as
+`hyperspec segments label <segments-file> <ids>=<label>[:key=value]...` does it without editing
+JSON by hand: `s1,s4=aside`, `s3=quote:speaker=gary-sheng`, `s2=claim:own=true`. Offsets and text
+never change, an unknown id or a label outside the set is refused with nothing written, and it
+prints what is still unlabeled. You may also move a boundary by hand, splitting one segment in two or joining two, as long as
 the rules under [Coverage](#coverage) still hold.
 
 ### The segments file
@@ -482,9 +486,31 @@ fails test 1.
 
 The header's `sha256` pins the material as it was when it was marked. If the material changes,
 lint fails the segments file as stale (test 4), because its offsets and labels describe text that
-is no longer there. Mark it again: run `segments init` with `--out` to a new file, point the
-material item at it, and label every segment, carrying labels over from the old file wherever the
-text did not change.
+is no longer there. Mark it again, keeping the labels of every stretch of text that did not change:
+
+```bash
+npx @supersuit/hyperspec segments init materials/voice-memo.md --id voice-memo --keep materials/voice-memo.md.segments.jsonl
+```
+
+`--keep <old>` splits the material as it reads now, and every segment whose text, trimmed, a
+segment in `<old>` has keeps that segment's `id`, its `label` and every other key it carries
+(`own`, `source`, `teller`, `speaker`, anything added by hand), with its `start` and `end` taken
+from the new split. The `id` is kept because the spine cites segments by id, so a citation keeps
+pointing at the words it pointed at. Old segments with the same text are used in order, each once.
+A segment no old one matches is new or changed text: it starts `unlabeled`, gets the next `s<n>` id
+no old segment used, and is listed with the start of its text, so only those need a label.
+`--keep` may name the file being written, which is how a material is re-marked in place; with no
+`--keep`, or one naming another file, an existing file is still never overwritten. It exits 2 when
+the `--keep` file cannot be read, has a line that is not a JSON object, or marks a material other
+than `--id`.
+
+After the author's framing line, s4, is edited to "and I kept the note in my wallet.", that prints:
+
+```text
+5 segments written to materials/voice-memo.md.segments.jsonl, 4 labels carried from materials/voice-memo.md.segments.jsonl, 1 to label:
+  s6 "My first manager said this to me in my second week, and I ke..."
+Label each one (claim, story, quote, stance, question, aside, private), then run hyperspec lint on the spec.
+```
 
 The hash is over the file's bytes, so a change nobody would call an edit still counts. Converting
 line endings is the common one: a material marked with LF endings reads as stale once an editor
@@ -821,6 +847,10 @@ against the draft:
 npx @supersuit/hyperspec check essay.hyperspec.md --draft essay/draft.md
 ```
 
+A draft is read as a reader sees it: a leading YAML frontmatter block and every HTML comment
+are blanked line for line, so a kept document (a title, a status, a note to self) grades exactly
+as its prose does, and every line number is still the file's own.
+
 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 nine stations in a fixed order and prints one line for each: `pass`,
@@ -1146,7 +1176,10 @@ marks and any parenthetical dropped. An item that says `(from Lesson 3)` reminds
 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
+use "context", and "skills" does not use "skill". A word inside a longer defined term is not a
+use of the shorter one: with "level" and "thinking level" both defined, "thinking level" and
+"thinking levels" use only "thinking level", while "level" on its own still uses "level". The quiz
+rules read a question the same way. 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.
@@ -1841,6 +1874,27 @@ cannot be read. `--json` prints the whole result.
 | `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 |
 
+## Is it ready
+
+```bash
+npx @supersuit/hyperspec ready essay.hyperspec.md --draft essay/draft.md
+```
+
+`hyperspec ready <spec> [--draft <file>] [--judges a,b] [--json]` answers one question for a
+tool that hands a draft on (to a person, to a send step): has THIS draft been through the engine
+under THIS spec? It reads the runs ledger and runs nothing. Ready means all three:
+
+- the latest full check of these exact draft and spec bytes passed (an `--only` run proves
+  nothing about the stations it skipped);
+- every required judge has a line for the same bytes and the latest passed; required is the
+  `--judges` list, or every judgment station that applies to the spec and draft, and the panel
+  needs a line for every reader, the buyer included;
+- that check comes after the last of those judge lines, so the panel's findings went to triage
+  and a check held every answer.
+
+It exits 0 ready, 1 not ready with each missing step listed, 2 usage. Edit the draft or the spec
+and it is not ready until it is graded again, because every rule is about the bytes.
+
 ## Learning from edits
 
 A factory writes a first draft, and a person edits it into the draft they approve. Every edit is

package/bin/hyperspec.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, statSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { existsSync, statSync, writeFileSync, readFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname, resolve, join } from "node:path";
 import { loadSpec } from "../src/load.mjs";
 import { lintSpec } from "../src/rules.mjs";
@@ -12,7 +12,7 @@ import { approve } from "../src/writer.mjs";
 import { reproduce } from "../src/reproduce.mjs";
 import { regenerate } from "../src/regenerate.mjs";
 import { compare } from "../src/compare.mjs";
-import { splitSegments } from "../src/segments.mjs";
+import { splitSegments, carrySegments, labelSegments } from "../src/segments.mjs";
 import { sha256 } from "../src/hash.mjs";
 import { readScope, measureFeatures, writeFeatures, scopeTemplate, GOLDENS_README } from "../src/dna.mjs";
 import { str } from "../src/placeholder.mjs";
@@ -21,6 +21,7 @@ import { prepareJudges, recordJudgment } from "../src/judge.mjs";
 import { prepareLearn, recordLearn, tallyLine } from "../src/learn.mjs";
 import { triageContext, triageState, answerFinding, importReview, replyText } from "../src/triage.mjs";
 import { sourceAt } from "../src/sequence-draft.mjs";
+import { ready } from "../src/ready.mjs";
 
 const HELP = `hyperspec <command> [options]
 
@@ -41,6 +42,14 @@ const HELP = `hyperspec <command> [options]
                                exit 0 every run station passed, 1 a station failed, 2 usage
                                (including a missing draft file, a spec without the writing
                                profile, or an --only that names no known station)
+  ready <spec> [--draft <file>] [--judges a,b] [--json]
+                               has this draft been through the engine under this spec? read from
+                               the runs ledger only: the latest full check of these exact draft
+                               and spec bytes passed, every required judge (the --judges list, or
+                               every judge that applies; each panel reader, the buyer included)
+                               passed on the same bytes, and that check came after the last of
+                               those judge lines, so panel findings were triaged and held
+                               exit 0 ready, 1 not ready (each missing step listed), 2 usage
   judge prepare <spec> --draft <file> --out <dir> [--only a,b] [--force] [--json]
                                needs a writing spec that passes lint (exits with lint's own code
                                otherwise); writes one <station>.packet.json per applicable
@@ -125,16 +134,28 @@ const HELP = `hyperspec <command> [options]
                                writing, --kind with it (use --form), or a folder that does not
                                exist
 
-  segments init <material> --id <mid> [--out <file>] [--by paragraph|sentence]
+  segments init <material> --id <mid> [--out <file>] [--by paragraph|sentence] [--keep <old>]
                                split a material into candidate segments, written as JSONL to
                                <material>.segments.jsonl by default; every segment starts label:
                                unlabeled, never valid in lint; label each one by hand (claim,
                                story, quote, stance, question, aside, private), then run hyperspec
                                lint on the spec; --by sentence also starts a segment at each list
-                               item (-, *, +, 1. or 1) then a space); refuses to overwrite an
-                               existing file (exit 2); exit 2 for a missing material, a material
-                               with nothing in it, an --out folder that does not exist, or a --by
-                               outside paragraph/sentence
+                               item (-, *, +, 1. or 1) then a space); --keep re-marks an edited
+                               material: every segment whose text, trimmed, an old segment in
+                               <old> has keeps that segment's id, label and every other key, and
+                               the rest are listed to label; refuses to overwrite an existing
+                               file unless --keep names it (exit 2); exit 2 for a missing
+                               material, a material with nothing in it, an --out folder that does
+                               not exist, a --by outside paragraph/sentence, or a --keep file that
+                               cannot be read, has a line that is not a JSON object, or marks
+                               another material
+
+  segments label <segments-file> <ids>=<label>[:key=value]...
+                               label segments in place: ids a comma list (s1,s4), the label from
+                               the closed set, then per-label fields (speaker=, teller=, source=,
+                               own=true); offsets and text are never touched; refuses an unknown
+                               id, a label outside the set or a malformed assignment with nothing
+                               written (exit 2); prints what is still unlabeled
 
   dna init <scope-dir> --writer W --form F --audience A --purpose P
                                write a new writer-DNA scope: scope.md (writer, form, audience,
@@ -225,7 +246,7 @@ if (cmd === "segments") {
   const sub = argv[1];
 
   if (sub === "init") {
-    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--id", "--out", "--by"] });
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--id", "--out", "--by", "--keep"] });
     if (parsed.error) { console.error(parsed.error); process.exit(2); }
     const [material] = parsed.positionals;
     if (!material) { console.error("segments init needs a material path"); process.exit(2); }
@@ -237,18 +258,73 @@ if (cmd === "segments") {
     try { materialStat = statSync(material); } catch { materialStat = null; }
     if (!materialStat || !materialStat.isFile()) { console.error(`material not found: ${material}`); process.exit(2); }
     const out = parsed.values["--out"] ?? `${material}.segments.jsonl`;
-    if (existsSync(out)) { console.error(`refusing to overwrite ${out}`); process.exit(2); }
+    const keep = parsed.values["--keep"];
+    // --keep may name the file being written: re-marking in place is the point. Nothing else is
+    // ever overwritten.
+    const samePath = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
+    if (existsSync(out) && !(keep && samePath(keep, out))) { console.error(`refusing to overwrite ${out}${keep ? " (--keep names a different file)" : ""}`); process.exit(2); }
     const outFolder = dirname(resolve(out));
     if (!existsSync(outFolder) || !statSync(outFolder).isDirectory()) { console.error(`folder does not exist: ${dirname(out)}; create it first`); process.exit(2); }
 
+    // The old segments to carry labels from: every line after the header, each a JSON object.
+    let old = null;
+    if (keep) {
+      let raw;
+      try { raw = readFileSync(keep, "utf8"); } catch { console.error(`--keep file not found: ${keep}`); process.exit(2); }
+      const rows = raw.split("\n").map((l, i) => ({ n: i + 1, l })).filter((r) => r.l.trim());
+      old = [];
+      for (const { n, l } of rows) {
+        let o;
+        try { o = JSON.parse(l); } catch { o = null; }
+        if (!o || typeof o !== "object" || Array.isArray(o)) { console.error(`--keep file ${keep} line ${n} is not a JSON object; fix it, or mark the material from scratch`); process.exit(2); }
+        if (n === 1) {
+          if (str(o.material) && str(o.material) !== id) { console.error(`--keep file ${keep} marks material "${o.material}", not "${id}"`); process.exit(2); }
+          continue;
+        }
+        old.push(o);
+      }
+    }
+
     const buf = readFileSync(material);
     const text = buf.toString("utf8");
     if (!/\S/.test(text)) { console.error(`nothing to mark: ${material} has no text`); process.exit(2); }
-    const segments = splitSegments(text, { by });
+    const fresh = splitSegments(text, { by });
+    const kept = old ? carrySegments(fresh, old) : null;
+    const segments = kept ? kept.segments : fresh;
     const header = { material: id, path: material, sha256: sha256(buf) };
     const lines = [JSON.stringify(header), ...segments.map((s) => JSON.stringify(s))];
     writeFileSync(out, `${lines.join("\n")}\n`);
-    console.log(`${segments.length} segments written to ${out}. Label every segment (claim, story, quote, stance, question, aside, private), then run hyperspec lint on the spec.`);
+    if (!kept) {
+      console.log(`${segments.length} segments written to ${out}. Label every segment (claim, story, quote, stance, question, aside, private), then run hyperspec lint on the spec.`);
+      process.exit(0);
+    }
+    const todo = kept.unlabeled;
+    console.log(`${segments.length} segments written to ${out}, ${kept.carried} labels carried from ${keep}, ${todo.length} to label${todo.length ? ":" : "."}`);
+    for (const s of todo) {
+      const t = s.text.replace(/\s+/g, " ").trim();
+      console.log(`  ${s.id} ${JSON.stringify(t.length > 60 ? `${t.slice(0, 60)}...` : t)}`);
+    }
+    console.log(todo.length
+      ? "Label each one (claim, story, quote, stance, question, aside, private), then run hyperspec lint on the spec."
+      : "Run hyperspec lint on the spec.");
+    process.exit(0);
+  }
+
+  if (sub === "label") {
+    const [file, ...assignments] = argv.slice(2);
+    if (!file || !assignments.length) { console.error("segments label needs a segments file and at least one <ids>=<label>[:key=value] assignment"); process.exit(2); }
+    let raw;
+    try { raw = readFileSync(file, "utf8"); } catch { console.error(`segments file not found: ${file}`); process.exit(2); }
+    const lines = raw.split("\n").filter((l) => l.trim());
+    let parsed;
+    try { parsed = lines.map((l) => JSON.parse(l)); } catch { console.error(`${file} has a line that is not JSON; fix it before labeling`); process.exit(2); }
+    const [header, ...segments] = parsed;
+    const done = labelSegments(segments, assignments);
+    if (done.error) { console.error(`segments label: ${done.error}; nothing written`); process.exit(2); }
+    writeFileSync(file, `${[header, ...done.segments].map((o) => JSON.stringify(o)).join("\n")}\n`);
+    const touched = new Set(assignments.flatMap((a) => a.slice(0, a.indexOf("=")).split(",").map((s) => s.trim())));
+    const todo = done.segments.filter((s) => s.label === "unlabeled").map((s) => s.id);
+    console.log(`${touched.size} segments labeled in ${file}${todo.length ? `; ${todo.length} still unlabeled: ${todo.join(", ")}` : "; every segment is labeled. Run hyperspec lint on the spec."}`);
     process.exit(0);
   }
 
@@ -373,6 +449,32 @@ if (cmd === "lint") {
   process.exit(worst);
 }
 
+if (cmd === "ready") {
+  const parsed = parseArgs(argv.slice(1), { valueFlags: ["--draft", "--judges"], boolFlags: ["--json"] });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [specPath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  const usage = (error) => {
+    if (json) console.log(JSON.stringify({ spec: specPath ?? null, draft: parsed.values["--draft"] ?? null, error }, null, 2));
+    else console.error(error);
+    process.exit(2);
+  };
+  if (!specPath) usage("ready needs a spec path");
+  let judges;
+  if (parsed.values["--judges"] !== undefined) {
+    judges = parsed.values["--judges"].split(",").map((s) => s.trim()).filter(Boolean);
+    if (!judges.length) usage("--judges names no judge");
+  }
+  const r = ready(specPath, parsed.values["--draft"], { judges });
+  if (r.usage) usage(r.error);
+  if (json) console.log(JSON.stringify({ spec: specPath, draft: r.draft, ready: r.ready, judges: r.judges, missing: r.missing }, null, 2));
+  else {
+    console.log(r.ready ? `ready: checked and judged (${r.judges.join(", ")}) on these exact bytes` : "not ready:");
+    for (const m of r.missing) console.log(`  - ${m}`);
+  }
+  process.exit(r.code);
+}
+
 if (cmd === "check") {
   const parsed = parseArgs(argv.slice(1), { valueFlags: ["--draft", "--only"], boolFlags: ["--json"] });
   if (parsed.error) { console.error(parsed.error); process.exit(2); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/hyperspec",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A hyperspec is a spec written for an agent: every decision accounted for, every requirement failable and checked, every field traced. The standard and its linter.",
   "type": "module",
   "bin": {

package/src/draft.mjs

@@ -21,6 +21,20 @@ export function splitLines(text) {
 export function readDraft(draftPathArg) {
   let buf;
   try { buf = readFileSync(resolve(draftPathArg)); } catch { return null; }
-  const text = buf.toString("utf8").replace(/^/, "");
+  const text = hideUnseen(buf.toString("utf8").replace(/^\uFEFF/, ""));
   return { path: draftPathArg, text, lines: splitLines(text), sha256: sha256(buf) };
 }
+
+// WHAT A READER NEVER SEES IS NOT PROSE (0.10). A leading YAML frontmatter block and every HTML
+// comment are blanked line for line: their characters go and their line breaks stay, so every
+// line number a finding names is still the file's own. A draft that is a kept document (a title,
+// a status, a note to self about what it was meant to be) then grades exactly as its prose does:
+// no hidden word counts toward length, is a term's first use, or needs a claim. Sequence drafts
+// already blanked frontmatter per file (src/sequence-draft.mjs); this is the same rule for every
+// draft. Offsets inside a line can move; evidence is matched by text, never by column.
+export function hideUnseen(text) {
+  const blank = (s) => s.replace(/[^\n]/g, "");
+  return text
+    .replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/, blank)
+    .replace(/<!--[\s\S]*?-->/g, blank);
+}

package/src/ready.mjs

@@ -0,0 +1,78 @@
+// `hyperspec ready` (0.10): has this draft, under this spec, been through the engine?
+//
+// Answered from the runs ledger alone (improvement.ledger), never by running a station or a judge,
+// so a caller can gate a handoff on it cheaply and deterministically: a drafting loop before it
+// shows a person the draft, a per-audience renderer before a version may be sent. Every rule
+// below is about the BYTES, the same hashes check and judge record write, so a draft or spec
+// edited after it was graded is never ready on the strength of grades it no longer has.
+//
+//   1. the latest FULL check of these draft and spec bytes passed (a partial --only run proves
+//      nothing about the stations it skipped);
+//   2. every required judge has a line for these bytes and its latest says pass; the panel needs
+//      one per reader, its buyer (the audience's own reader) included;
+//   3. that check is later in the ledger than every one of those judge lines, so the panel's
+//      findings went to triage and a check held every answer, instead of being recorded and left.
+//
+// Required judges: the caller's list, or every judgment station that applies to this spec and
+// draft (src/judges/index.mjs skipReason is null).
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadWritingSpec } from "./check.mjs";
+import { readDraft } from "./draft.mjs";
+import { readSequenceDraft, sequenceFilesDecl } from "./sequence-draft.mjs";
+import { openLedger } from "./ledger.mjs";
+import { sha256 } from "./hash.mjs";
+import { JUDGES, JUDGE_NAMES } from "./judges/index.mjs";
+
+const present = (v) => typeof v === "string" && v.trim().length > 0;
+
+export function ready(specPathArg, draftPathArg, { judges } = {}) {
+  const loaded = loadWritingSpec(specPathArg, "ready");
+  if (loaded.usage) return { usage: true, error: loaded.error };
+  const { spec } = loaded;
+  const fromSequence = !present(draftPathArg);
+  if (fromSequence && !sequenceFilesDecl(spec).length) return { usage: true, error: "ready needs --draft <file>" };
+  if (judges) {
+    const unknown = judges.filter((j) => !JUDGE_NAMES.includes(j));
+    if (unknown.length) return { usage: true, error: `unknown judge${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}; known: ${JUDGE_NAMES.join(", ")}` };
+  }
+  const draft = fromSequence ? readSequenceDraft(spec, specPathArg) : readDraft(draftPathArg);
+  if (!draft) return { usage: true, error: `cannot read draft: ${draftPathArg ?? "the sequence files"}` };
+  const specSha = sha256(readFileSync(resolve(specPathArg)));
+
+  const required = judges ?? JUDGES.filter((j) => j.skipReason(spec, draft) === null).map((j) => j.name);
+  const ledger = openLedger(spec);
+  const missing = [];
+  if (!ledger || ledger.warning) {
+    missing.push(ledger?.warning ?? "the spec declares no improvement.ledger, so nothing it was graded on is recorded");
+    return { ok: true, ready: false, judges: required, missing, code: 1 };
+  }
+  const lines = ledger.priorText.split("\n").filter((l) => l.trim())
+    .map((l, i) => { try { return { ...JSON.parse(l), _n: i }; } catch { return null; } })
+    .filter((l) => l && l.draft_sha256 === draft.sha256 && l.spec_sha256 === specSha);
+
+  const check = lines.filter((l) => l.kind === "check" && l.partial !== true).at(-1);
+  if (!check) missing.push("no full check of this draft under this spec; run hyperspec check");
+  else {
+    const failing = Object.entries(check.stations ?? {}).filter(([, s]) => s === "fail").map(([n]) => n);
+    if (failing.length) missing.push(`the last check failed: ${failing.join(", ")}`);
+  }
+
+  let lastJudge = -1;
+  for (const name of required) {
+    const judge = JUDGES.find((j) => j.name === name);
+    const of = lines.filter((l) => l.kind === "judge" && l.station === name);
+    const variants = judge.variants ? judge.variants(spec).map((v) => v.id) : [null];
+    for (const v of variants) {
+      const label = v ? `${name} (${v})` : name;
+      const last = of.filter((l) => (v ? l.reader === v : true)).at(-1);
+      if (!last) { missing.push(`${label} has not judged this draft under this spec`); continue; }
+      lastJudge = Math.max(lastJudge, last._n);
+      if (last.status !== "pass") missing.push(`${label} did not pass: ${last.status}`);
+    }
+  }
+  if (check && lastJudge > check._n) missing.push("a judge recorded after the last check; run hyperspec check again so its findings are held");
+
+  return { ok: true, ready: missing.length === 0, judges: required, missing, draft: draft.path, code: missing.length ? 1 : 0 };
+}

package/src/segments.mjs

@@ -182,6 +182,50 @@ export function splitSegments(text, { by = "paragraph" } = {}) {
   return spans.map((s, i) => ({ id: `s${i + 1}`, start: s.start, end: s.end, label: "unlabeled", text: text.slice(s.start, s.end) }));
 }
 
+// -------------------------------------------------------------------------------------------
+// carrySegments: re-marking an edited material without relabeling what did not change (0.9.1).
+// A label is a fact about a stretch of text, so while the same text (compared trimmed) is still in
+// the material, its label is still true. `fresh` is what splitSegments returned for the material as
+// it reads now; `old` is the segment objects of the file it was marked in before. Each fresh
+// segment whose trimmed text an old segment has takes that old segment's id, label and every other
+// key it carries (own, source, teller, speaker, anything a person added), with start, end and text
+// from the new split. The id is carried too, because the spine cites segments by id: "m1#s3" keeps
+// pointing at the words it pointed at. Old segments with the same text are used in document order,
+// each once. A fresh segment no old one matches stays "unlabeled" and gets the next id no old
+// segment used, "s<n>" counting up past the highest. Returns { segments, carried, unlabeled }:
+// carried counts the segments that took a label other than "unlabeled"; unlabeled lists every
+// segment still to label, in document order.
+export function carrySegments(fresh, old) {
+  const byText = new Map();
+  for (const o of old) {
+    if (!o || typeof o !== "object" || typeof o.text !== "string") continue;
+    const k = o.text.trim();
+    if (!byText.has(k)) byText.set(k, []);
+    byText.get(k).push(o);
+  }
+  const taken = new Set(old.map((o) => str(o?.id)).filter(Boolean));
+  let n = Math.max(0, ...[...taken].map((id) => Number(/^s(\d+)$/.exec(id)?.[1] ?? 0)));
+  const nextId = () => {
+    do n += 1; while (taken.has(`s${n}`));
+    taken.add(`s${n}`);
+    return `s${n}`;
+  };
+  const segments = [];
+  let carried = 0;
+  for (const seg of fresh) {
+    const match = byText.get(seg.text.trim())?.shift();
+    if (!match) {
+      segments.push({ id: nextId(), start: seg.start, end: seg.end, label: "unlabeled", text: seg.text });
+      continue;
+    }
+    const { id, start, end, label, text, ...extra } = match;
+    const kept = { id: str(id) || nextId(), start: seg.start, end: seg.end, label: typeof label === "string" && label ? label : "unlabeled", ...extra, text: seg.text };
+    if (kept.label !== "unlabeled") carried += 1;
+    segments.push(kept);
+  }
+  return { segments, carried, unlabeled: segments.filter((s) => s.label === "unlabeled") };
+}
+
 // -------------------------------------------------------------------------------------------
 // readSegments: parse + validate a marked-up segments file. Never throws on a bad or missing
 // file; every failure mode becomes a finding in the lint shape (test, id, severity, message, fix),
@@ -405,3 +449,43 @@ export function readSegments(segmentsPath, { materialPath, materialId, displayPa
 
   return { header, segments, findings };
 }
+
+// ── labeling (0.10) ──────────────────────────────────────────────────────────────────────────
+// One assignment is "<ids>=<label>[:key=value]...": ids a comma list ("s1,s4"), the label from the
+// closed set, then any per-label fields (speaker=, teller=, source=, own=true). own's "true" is
+// written as the boolean the format reads. Parsed and applied as pure data so a caller (the CLI,
+// a capture stage) can label without hand-editing JSONL, and so a bad assignment is refused
+// before anything is written: { segments } on success, { error } on the first problem.
+export function parseLabelAssignment(raw) {
+  const eq = String(raw).indexOf("=");
+  if (eq < 1) return { error: `"${raw}" is not <ids>=<label>[:key=value]...` };
+  const ids = raw.slice(0, eq).split(",").map((s) => s.trim()).filter(Boolean);
+  const [label, ...pairs] = raw.slice(eq + 1).split(":");
+  if (!MATERIAL_LABELS.includes(label)) return { error: `"${label}" is not a label; use one of ${MATERIAL_LABELS.join(", ")}` };
+  const fields = {};
+  for (const p of pairs) {
+    const k = p.indexOf("=");
+    if (k < 1) return { error: `"${p}" in "${raw}" is not key=value` };
+    const key = p.slice(0, k).trim();
+    if (["id", "start", "end", "text", "label"].includes(key)) return { error: `"${key}" is set by marking, not by a label assignment` };
+    const value = p.slice(k + 1);
+    fields[key] = key === "own" && value === "true" ? true : value;
+  }
+  return { ids, label, fields };
+}
+
+export function labelSegments(segments, assignments) {
+  const out = segments.map((s) => ({ ...s }));
+  const byId = new Map(out.map((s) => [s.id, s]));
+  for (const raw of assignments) {
+    const a = parseLabelAssignment(raw);
+    if (a.error) return { error: a.error };
+    for (const id of a.ids) {
+      const s = byId.get(id);
+      if (!s) return { error: `no segment "${id}" in this file` };
+      s.label = a.label;
+      Object.assign(s, a.fields);
+    }
+  }
+  return { segments: out };
+}

package/src/sequence-draft.mjs

@@ -7,7 +7,7 @@ import { readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, posix, resolve } from "node:path";
 import { sha256 } from "./hash.mjs";
 import { str } from "./placeholder.mjs";
-import { splitLines } from "./draft.mjs";
+import { splitLines, hideUnseen } from "./draft.mjs";
 
 const list = (v) => (Array.isArray(v) ? v : []);
 const byNumber = (a, b) => a.localeCompare(b, "en", { numeric: true });
@@ -44,8 +44,8 @@ export function sequenceFiles(specDir, entries) {
 // { path, text, lines, sha256, sources }, the same shape src/draft.mjs's readDraft returns plus
 // sources, one per file: { file, at, startLine, lineCount }. file is the path relative to the spec
 // (what a finding names); at resolves from the working directory (what a station opens, such as
-// links resolving a relative link beside the file that holds it). Each file's YAML frontmatter is
-// blanked line for line, so its metadata is not prose and its line numbers stay its own. sha256
+// links resolving a relative link beside the file that holds it). Each file's YAML frontmatter and HTML comments are
+// blanked line for line (src/draft.mjs's hideUnseen), so its metadata is not prose and its line numbers stay its own. sha256
 // covers every file's name and bytes. path is the first file's. null when no file matches.
 export function readSequenceDraft(spec, specPathArg) {
   const files = sequenceFiles(spec.dir, sequenceFilesDecl(spec));
@@ -58,7 +58,7 @@ export function readSequenceDraft(spec, specPathArg) {
     const buf = readFileSync(resolve(spec.dir, file));
     hashed.push(Buffer.from(`${file}\n`), buf);
     let text = buf.toString("utf8").replace(/^\uFEFF/, "");
-    text = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, (fm) => fm.replace(/[^\n]/g, ""));
+    text = hideUnseen(text);
     if (!text.endsWith("\n")) text += "\n";
     const lineCount = text.split("\n").length - 1;
     sources.push({ file, at: join(dirname(specPathArg), file), startLine, lineCount });

package/src/spec-text.mjs

@@ -0,0 +1,85 @@
+// specText(data, body) (0.10): a hyperspec file's text from data, for a tool that BUILDS specs
+// rather than a person typing one: a drafting loop filling a skeleton's mechanical blocks, a
+// renderer writing one spec per audience. Writes the block-style YAML subset hyperspec reads
+// (maps, lists of scalars, lists of maps, scalars), quoting every scalar the way init does
+// (template.mjs's scalar), then READS IT BACK with the same reader lint uses and throws, naming
+// the field, if any value came back different. A lossy spec is never handed over: hand-written
+// YAML once lost everything after " #" and after a leading quoted phrase while lint passed
+// (letter BUILD-NOTES item 1).
+//
+// Every scalar reads back as a string (the reader's own rule), so numbers and booleans are
+// written plain and compared as text. null and nested lists have no form here and are refused.
+import { parseSkillFile } from "@supersuit/superskill/yaml";
+import { scalar } from "./template.mjs";
+
+const isMap = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+
+function emitScalar(v, at) {
+  if (typeof v === "string") return scalar(v);
+  if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  if (typeof v === "boolean") return String(v);
+  throw new Error(`specText: ${at} is ${v === null ? "null" : typeof v}, which a hyperspec cannot hold; write a string or leave the key out`);
+}
+
+function emitMap(obj, indent, at) {
+  const pad = " ".repeat(indent);
+  const out = [];
+  for (const [k, v] of Object.entries(obj)) {
+    if (v === undefined) continue;
+    const here = at ? `${at}.${k}` : k;
+    if (Array.isArray(v)) {
+      if (!v.length) { out.push(`${pad}${k}: []`); continue; }
+      out.push(`${pad}${k}:`);
+      v.forEach((item, i) => out.push(...emitItem(item, indent + 2, `${here}[${i}]`)));
+    } else if (isMap(v)) {
+      if (!Object.keys(v).length) throw new Error(`specText: ${here} is an empty map, which reads back as nothing; leave the key out`);
+      out.push(`${pad}${k}:`, ...emitMap(v, indent + 2, here));
+    } else out.push(`${pad}${k}: ${emitScalar(v, here)}`);
+  }
+  return out;
+}
+
+function emitItem(item, indent, at) {
+  const pad = " ".repeat(indent);
+  if (Array.isArray(item)) throw new Error(`specText: ${at} is a list inside a list, which a hyperspec cannot hold`);
+  if (!isMap(item)) return [`${pad}- ${emitScalar(item, at)}`];
+  const lines = emitMap(item, indent + 2, at);
+  if (!lines.length) throw new Error(`specText: ${at} is an empty map`);
+  return [`${pad}- ${lines[0].slice(indent + 2)}`, ...lines.slice(1)];
+}
+
+// Scalars compared as the reader returns them: text.
+const norm = (v) => (Array.isArray(v) ? v.map(norm) : isMap(v)
+  ? Object.fromEntries(Object.entries(v).filter(([, x]) => x !== undefined).map(([k, x]) => [k, norm(x)]))
+  : String(v));
+
+function firstDiff(a, b, at = "") {
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return at || "(root)";
+    for (let i = 0; i < a.length; i++) { const d = firstDiff(a[i], b[i], `${at}[${i}]`); if (d) return d; }
+    return null;
+  }
+  if (isMap(a) || isMap(b)) {
+    if (!isMap(a) || !isMap(b)) return at || "(root)";
+    for (const k of new Set([...Object.keys(a), ...Object.keys(b)])) { const d = firstDiff(a[k], b[k], at ? `${at}.${k}` : k); if (d) return d; }
+    return null;
+  }
+  return a === b ? null : at;
+}
+
+export function specText(data, body = "") {
+  if (!isMap(data)) throw new Error("specText: data must be an object");
+  const text = `---\n${emitMap(data, 0, "").join("\n")}\n---\n${body}`;
+  const { data: readBack, error } = parseSkillFile(text);
+  if (error) throw new Error(`specText: the reader refused the result: ${error}`);
+  const diff = firstDiff(norm(data), readBack);
+  if (diff) throw new Error(`specText: ${diff} does not read back as written; nothing returned`);
+  return text;
+}
+
+// The reading half: a spec's text as lint reads it, { data, body, error }. With specText, a tool
+// can read a skeleton (`hyperspec init --profile writing`), fill the blocks it knows, and write
+// it back without a second YAML reader that disagrees with the linter.
+export function parseSpecText(text) {
+  return parseSkillFile(String(text ?? ""));
+}

package/src/stations/sequence.mjs

@@ -27,7 +27,11 @@
 //              way used, so the rules and the question shape are that checker's.
 //
 // A use is a whole-word, case-insensitive match, where a hyphen is part of a word: "context-aware"
-// does not use "context", and "skills" does not use "skill". The station reads the outline from
+// does not use "context", and "skills" does not use "skill". A word inside a longer defined term is
+// not a use of the shorter one (hyperspec 0.9.1): with "level" and "thinking level" both defined,
+// "thinking level" and "thinking levels" use only "thinking level", and "level" on its own still
+// uses "level". Every guard that looks for a use (order, quiz order, quiz coverage) masks the
+// longer terms first. The station reads the outline from
 // disk, resolved against the spec's folder, the way claims reads its ledger. It never reads a
 // part's text for meaning: a term used in a sense other than its definition still counts as a use.
 
@@ -202,6 +206,25 @@ function firstUse(unit, prose, term) {
 // Whether `text` (code already masked) uses `term`, by the same whole-word rule as firstUse.
 const usesTerm = (text, term) => new RegExp(`(^|[^a-z0-9-])${escapeRe(term)}([^a-z0-9-]|$)`, "i").test(text);
 
+// For each defined term, the other defined terms that contain it as a whole-word phrase, longest
+// first: { level: ["thinking level"] }. A term no other term contains maps to [].
+export function longerTerms(terms) {
+  const all = [...terms];
+  return new Map(all.map((t) => [t, all.filter((u) => u !== t && usesTerm(u, t)).sort((a, b) => b.length - a.length)]));
+}
+
+// `text` with every whole-word occurrence of each `longer` term, a trailing plural "s" included,
+// blanked to spaces. Line breaks survive, so a line number still maps to the same line, and a term
+// broken across two lines is blanked on both.
+export function maskLonger(text, longer) {
+  let out = text;
+  for (const t of longer) {
+    const re = new RegExp(`(?<![a-z0-9-])${escapeRe(t).replace(/ /g, "\\s+")}s?(?![a-z0-9-])`, "gi");
+    out = out.replace(re, (m) => m.replace(/[^\n]/g, " "));
+  }
+  return out;
+}
+
 // Every quiz in the draft, read the way the first book written to this shape wrote it:
 //
 //   ## Check yourself: Part 1
@@ -308,12 +331,17 @@ export function run(spec, draft) {
   }
 
   // order: no unit before the defining one uses the term.
+  // A longer defined term that contains the term is masked first: "thinking level" is not a use of
+  // "level".
   const prose = new Map(units.map((u) => [u, proseOf(u, seq, { withTerms: false })]));
+  const longer = longerTerms(definedAt.keys());
   for (const [t, at] of definedAt) {
     if (seq.knows.has(t)) continue;
+    const sups = longer.get(t);
     for (const u of units) {
       if (u === at) break;
-      const line = firstUse(u, prose.get(u), t);
+      const lines = sups.length ? maskLonger(prose.get(u).join("\n"), sups).split("\n") : prose.get(u);
+      const line = firstUse(u, lines, t);
       if (line) findings.push(finding({ id: "station-sequence-used-before-defined", severity: "fail", message: `${U} ${u.n} uses "${t}" before ${U} ${at.n} defines it`, fix: `Rewrite ${U} ${u.n} without "${t}", define it earlier, or add it to writing.form.sequence.knows if the reader already has the word.`, line: line }));
     }
   }
@@ -362,6 +390,12 @@ function quizFindings(draft, seq, definedAt) {
   const U = seq.unit;
   const out = [];
   const { quizzes, questions, untagged } = parseQuizzes(draft, seq);
+  // Every question's text with each term's longer defined terms masked, as the order guard reads
+  // prose: "thinking level" in a question neither uses nor tests "level".
+  const longer = longerTerms(definedAt.keys());
+  const masked = (q, t) => (longer.get(t).length ? maskLonger(q.text, longer.get(t)) : q.text);
+  const uses = (q, t) => usesTerm(masked(q, t), t);
+  const tests = (q, t) => { const text = masked(q, t); return usesTerm(text, t) || usesTerm(text, `${t}s`); };
   if (!quizzes) {
     return [finding({ id: "station-sequence-quiz-missing", severity: "fail", message: `no "${seq.quiz}" heading in the draft, and writing.form.sequence.quiz names one`, fix: `Add a "## ${seq.quiz}" section of questions, or delete quiz: from the spec.` })];
   }
@@ -375,12 +409,12 @@ function quizFindings(draft, seq, definedAt) {
     }
     for (const [t, at] of definedAt) {
       if (seq.knows.has(t) || at.n <= q.unit) continue;
-      if (usesTerm(q.text, t)) out.push(finding({ id: "station-sequence-quiz-used-before-defined", severity: "fail", message: `question ${q.n}, tagged ${U} ${q.unit}, uses "${t}", which ${U} ${at.n} defines later`, fix: `Rewrite the question without "${t}", or tag it with ${U} ${at.n} or later.`, line: q.line }));
+      if (uses(q, t)) out.push(finding({ id: "station-sequence-quiz-used-before-defined", severity: "fail", message: `question ${q.n}, tagged ${U} ${q.unit}, uses "${t}", which ${U} ${at.n} defines later`, fix: `Rewrite the question without "${t}", or tag it with ${U} ${at.n} or later.`, line: q.line }));
     }
   }
   // coverage: a simple plural counts, so "skills" tests "skill".
   for (const [t, at] of definedAt) {
-    if (!questions.some((q) => usesTerm(q.text, t) || usesTerm(q.text, `${t}s`))) {
+    if (!questions.some((q) => tests(q, t))) {
       out.push(finding({ id: "station-sequence-quiz-untested", severity: "fail", message: `no quiz question tests "${t}", which ${U} ${at.n} defines`, fix: `Add a question that uses "${t}", tagged ${U} ${at.n} or later.`, line: at.line }));
     }
   }

package/src/writing-exports.mjs

@@ -9,3 +9,6 @@
 export { MATERIAL_LABELS } from "./labels.mjs";
 export { readSegments } from "./segments.mjs";
 export { readScope, measureFeatures } from "./dna.mjs";
+// specText writes a spec's text from data and refuses anything the reader would not return
+// unchanged, for a tool that builds specs (0.10).
+export { specText, parseSpecText } from "./spec-text.mjs";