@supersuit/hyperspec 0.9.1 → 0.10.0

package/CHANGELOG.md

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

package/README.md

@@ -26,9 +26,11 @@ improvement ledger. Every test is defined in [SPEC.md](SPEC.md).
 | `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] [--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.1** (2026-09-30)
+**Version 0.10.0** (2026-10-02)
 
 ## What makes a spec a hyperspec
 

package/WRITING.md

@@ -408,7 +408,10 @@ exist or a `--by` it does not know, a material with nothing in it, and an `--out
 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
@@ -844,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`,
@@ -1867,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

@@ -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, carrySegments } 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
@@ -141,6 +150,13 @@ const HELP = `hyperspec <command> [options]
                                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,
                                purpose) and an empty goldens/ folder holding a README on the
@@ -294,6 +310,24 @@ if (cmd === "segments") {
     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);
+  }
+
   console.error(`unknown segments subcommand: ${sub}\n\n${HELP}`);
   process.exit(2);
 }
@@ -415,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.1",
+  "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

@@ -449,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/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";