@supersuit/hyperspec 0.3.0 → 0.5.0

package/bin/hyperspec.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { existsSync, statSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, statSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
 import { loadSpec } from "../src/load.mjs";
 import { lintSpec } from "../src/rules.mjs";
 import { score, exitCode } from "../src/score.mjs";
@@ -12,6 +12,10 @@ 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 { sha256 } from "../src/hash.mjs";
+import { readScope, measureFeatures, writeFeatures, scopeTemplate, GOLDENS_README } from "../src/dna.mjs";
+import { str } from "../src/placeholder.mjs";
 
 const HELP = `hyperspec <command> [options]
 
@@ -30,6 +34,34 @@ 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]
+                               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
+
+  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
+                               golden file shape (why, approved_by, source, optional approved_on;
+                               the body is the passage, verbatim); refuses to overwrite an
+                               existing scope.md; exit 2 on a missing parent folder, a missing
+                               flag, or a flag value that looks like a placeholder (todo, ..., a
+                               bare -), never a stack trace
+  dna measure <scope-dir> [--json]
+                               read every golden in <scope-dir>/goldens/, check its required
+                               fields, and write <scope-dir>/features.json: deterministic style
+                               features measured from the goldens' text, never judged and never
+                               run through a model
+                               exit 0 wrote features.json, 1 a golden (or the scope itself) fails
+                               a required-field check, so a hollow golden is never measured into
+                               the DNA, 2 usage
+
   recipe check <output-or-recipe> [--json]
                                check a recipe's completeness (a path not ending .recipe.json
                                means <path>.recipe.json)
@@ -98,6 +130,128 @@ if (cmd === "init") {
   process.exit(0);
 }
 
+if (cmd === "segments") {
+  const sub = argv[1];
+
+  if (sub === "init") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--id", "--out", "--by"] });
+    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); }
+    if (!parsed.values["--id"]) { console.error("segments init needs --id <material id>"); process.exit(2); }
+    const id = parsed.values["--id"];
+    const by = parsed.values["--by"] ?? "paragraph";
+    if (by !== "paragraph" && by !== "sentence") { console.error(`--by must be paragraph or sentence, not "${by}"`); process.exit(2); }
+    let materialStat;
+    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 outFolder = dirname(resolve(out));
+    if (!existsSync(outFolder) || !statSync(outFolder).isDirectory()) { console.error(`folder does not exist: ${dirname(out)}; create it first`); process.exit(2); }
+
+    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 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.`);
+    process.exit(0);
+  }
+
+  console.error(`unknown segments subcommand: ${sub}\n\n${HELP}`);
+  process.exit(2);
+}
+
+if (cmd === "dna") {
+  const sub = argv[1];
+
+  if (sub === "init") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--writer", "--form", "--audience", "--purpose"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [scopeDir] = parsed.positionals;
+    if (!scopeDir) { console.error("dna init needs a scope-dir path"); process.exit(2); }
+    for (const flagName of ["--writer", "--form", "--audience", "--purpose"]) {
+      if (!parsed.values[flagName]) { console.error(`dna init needs ${flagName} <value>`); process.exit(2); }
+    }
+    // A placeholder-looking value (todo, tbd, ..., ???, ...) is caught here rather than left
+    // for the next `dna measure` to catch on scope.md's own fields; str() is the one place that
+    // pattern is defined (src/placeholder.mjs), reused rather than re-checked.
+    for (const flagName of ["--writer", "--form", "--audience", "--purpose"]) {
+      if (!str(parsed.values[flagName])) {
+        console.error(`dna init ${flagName} "${parsed.values[flagName]}" looks like a placeholder; give it real content`);
+        process.exit(2);
+      }
+    }
+    const writer = parsed.values["--writer"];
+    const form = parsed.values["--form"];
+    const audience = parsed.values["--audience"];
+    const purpose = parsed.values["--purpose"];
+
+    const scopeAbs = resolve(scopeDir);
+    const parent = dirname(scopeAbs);
+    if (!existsSync(parent) || !statSync(parent).isDirectory()) {
+      console.error(`the folder ${dirname(scopeDir)} does not exist; create it first`);
+      process.exit(2);
+    }
+    if (existsSync(scopeAbs) && !statSync(scopeAbs).isDirectory()) {
+      console.error(`${scopeDir} is not a directory`);
+      process.exit(2);
+    }
+    // scopeMdPath (absolute, resolved from the cwd) is for filesystem operations only. Every
+    // message uses scopeMdDisplay, built from scopeDir exactly as given (relative, if that is how
+    // the operator typed it): a path the operator did not resolve themselves must never appear
+    // resolved in output, the same rule every other finding in this linter already follows.
+    const scopeMdPath = join(scopeAbs, "scope.md");
+    const scopeMdDisplay = join(scopeDir, "scope.md");
+    if (existsSync(scopeMdPath)) { console.error(`refusing to overwrite ${scopeMdDisplay}`); process.exit(2); }
+
+    mkdirSync(join(scopeAbs, "goldens"), { recursive: true });
+    writeFileSync(scopeMdPath, scopeTemplate({ writer, form, audience, purpose }));
+    // An operator's own goldens/README.md is theirs: write the guidance only where none exists.
+    try {
+      writeFileSync(join(scopeAbs, "goldens", "README.md"), GOLDENS_README, { flag: "wx" });
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+    }
+    console.log(`wrote ${scopeMdDisplay} and ${scopeDir}/goldens/. Add goldens, then run: hyperspec dna measure ${scopeDir}`);
+    process.exit(0);
+  }
+
+  if (sub === "measure") {
+    const parsed = parseArgs(argv.slice(2), { boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [scopeDir] = parsed.positionals;
+    if (!scopeDir) { console.error("dna measure needs a scope-dir path"); process.exit(2); }
+    const json = parsed.values["--json"];
+
+    const { scope, goldens, findings } = readScope(scopeDir);
+    const hasFail = findings.some((x) => x.severity === "fail");
+    if (hasFail) {
+      if (json) console.log(JSON.stringify({ scope: scopeDir, findings }, null, 2));
+      else for (const x of findings) console.log(`fail [${x.test}] ${x.message}\n  fix: ${x.fix}`);
+      process.exit(1);
+    }
+
+    const features = measureFeatures(goldens.map((g) => g.text));
+    const { path: featuresPath } = writeFeatures(scopeDir, { scope, goldens, features });
+    if (json) {
+      console.log(JSON.stringify({ scope: scopeDir, goldens: goldens.length, features, wrote: featuresPath }, null, 2));
+    } else {
+      console.log(`${scopeDir}: measured ${goldens.length} golden${goldens.length === 1 ? "" : "s"}`);
+      console.log(`  word_count ${features.word_count}, sentence length mean ${features.sentence_length.mean} median ${features.sentence_length.median} p90 ${features.sentence_length.p90}`);
+      console.log(`  signature words: ${features.signature_words.join(", ") || "(none)"}`);
+      console.log(`wrote ${featuresPath}`);
+    }
+    process.exit(0);
+  }
+
+  console.error(`unknown dna subcommand: ${sub}\n\n${HELP}`);
+  process.exit(2);
+}
+
 if (cmd === "lint") {
   const json = argv.includes("--json");
   // Lint takes one flag, --json, and no flag takes a value, so a flag is dropped on its own and
@@ -359,7 +513,7 @@ if (cmd === "compare") {
   if (json) console.log(JSON.stringify(result, null, 2));
 
   // Both a usage error and a check-failed error (missing output, escaping path, ...) map to
-  // 2 here — compare's own ok:false without a usage flag is still "could not grade", i.e. an
+  // 2 here: compare's own ok:false without a usage flag is still "could not grade", i.e. an
   // unreadable-input class failure, not a graded-but-worse-1 class one.
   if (!result.ok) {
     if (!json) console.error(result.error);

package/examples/writing/dna/essay-new-managers-teach/features.json

@@ -0,0 +1,56 @@
+{
+  "dna": "0.1",
+  "scope": {
+    "writer": "example-author",
+    "form": "essay",
+    "audience": "new managers",
+    "purpose": "teach"
+  },
+  "goldens": [
+    {
+      "path": "goldens/close.md",
+      "sha256": "a90291714fc3bd79a16c613deb536b34c4ef577e56083c0c6b17142fbc4b871f"
+    },
+    {
+      "path": "goldens/opening.md",
+      "sha256": "395c7c37d604e255a07603276bac0d2f0915bc80d9acea45e3a30a6fe248b44e"
+    },
+    {
+      "path": "goldens/status.md",
+      "sha256": "891c34d9134380e5c752e69036ec9707729b7e30c9f2b3f2789b8d3ee3f311ed"
+    }
+  ],
+  "features": {
+    "word_count": 118,
+    "sentence_length": {
+      "mean": 13.111,
+      "median": 15,
+      "p90": 25
+    },
+    "paragraph_length": {
+      "mean_sentences": 3,
+      "mean_words": 39.333
+    },
+    "rates_per_1000_words": {
+      "comma": 33.898,
+      "semicolon": 0,
+      "colon": 8.475,
+      "em_dash": 0,
+      "en_dash": 0,
+      "exclamation": 0,
+      "question_mark": 0,
+      "parentheses": 0,
+      "quotation_marks": 0
+    },
+    "contraction_rate": 0,
+    "first_person_singular_rate": 0,
+    "first_person_plural_rate": 0,
+    "second_person_rate": 59.322,
+    "mean_word_length": 3.831,
+    "signature_words": [
+      "first",
+      "report",
+      "tracker"
+    ]
+  }
+}

package/examples/writing/dna/essay-new-managers-teach/goldens/README.md

@@ -0,0 +1,14 @@
+# Goldens
+
+Each file in this folder except this one is a golden: a passage the writer marked as right,
+filed under this scope.
+
+Frontmatter:
+- why (required): what makes it golden, the move it teaches.
+- approved_by (required): a person slug. Golden means a human approved it; agent:* is refused.
+- source (required): where the passage came from.
+- approved_on (optional): a date.
+
+The body is the passage, verbatim.
+
+Run `hyperspec dna measure <scope-dir>` once every golden here has why, approved_by and source.

package/examples/writing/dna/essay-new-managers-teach/goldens/close.md

@@ -0,0 +1,9 @@
+---
+why: ends on an instruction and gives the reason for it in the same sentence
+approved_by: example-author
+source: first draft of this essay's closing paragraph, marked golden on the review page
+approved_on: "2026-09-18"
+---
+
+So write the three questions on a card. Ask the first one. Then wait, longer than feels polite,
+because the first answer is the one they rehearsed and the second one is the one you came for.

package/examples/writing/dna/essay-new-managers-teach/goldens/opening.md

@@ -0,0 +1,9 @@
+---
+why: one plain claim in the first sentence, then two short sentences that turn it into something to do
+approved_by: example-author
+source: first draft of this essay's opening paragraph, marked golden on the review page
+approved_on: "2026-09-18"
+---
+
+Your first one-on-one with a new report is the only meeting on your calendar where they should
+set the agenda. Everything else you run. This one you hand over.

package/examples/writing/dna/essay-new-managers-teach/goldens/status.md

@@ -0,0 +1,10 @@
+---
+why: states what to stop doing, then where that thing already lives, then what the freed half hour is for, one sentence each
+approved_by: example-author
+source: an earlier newsletter essay for new managers by the same writer, its middle section
+approved_on: "2026-09-18"
+---
+
+If you can read it in the tracker, do not ask for it in the room. Status already has a home,
+and your report is the one who put it there. Spend the half hour on what the tracker cannot
+hold: how the work looks from their side of it.

package/examples/writing/dna/essay-new-managers-teach/scope.md

@@ -0,0 +1,11 @@
+---
+writer: example-author
+form: essay
+audience: new managers
+purpose: teach
+---
+
+# Writer DNA scope
+
+Goldens live in goldens/. Run `hyperspec dna measure <scope-dir>` once every golden there has
+why, approved_by and source.

package/examples/writing/essay/materials/interview-notes.md.segments.jsonl

@@ -0,0 +1,10 @@
+{"material":"interview","path":"essay/materials/interview-notes.md","sha256":"3c4fd3ff19435027b1bb9584e648128d59feb3184f67eeaf6b09ed9fa8bcfaeb"}
+{"id":"s1","start":0,"end":118,"label":"aside","text":"Interview notes, a thirty-minute call with an engineering manager of eight years, taken by the\nauthor during the call."}
+{"id":"s2","start":119,"end":199,"label":"aside","text":"Considered: the manager reviewed these notes afterwards and corrected two\nlines."}
+{"id":"s3","start":201,"end":240,"label":"claim","source":"interview with an engineering manager of eight years","text":"- Her rule: the report owns the agenda."}
+{"id":"s4","start":241,"end":356,"label":"claim","source":"interview with an engineering manager of eight years","text":"She keeps a shared document per person; they add items\n  before the meeting, and she adds hers last, at the bottom."}
+{"id":"s5","start":357,"end":448,"label":"quote","speaker":"the engineering manager interviewed","text":"- \"If I have something urgent, it is not a one-on-one topic. I send it the day it happens.\""}
+{"id":"s6","start":449,"end":617,"label":"claim","source":"interview with an engineering manager of eight years","text":"- The first one-on-one with a new report is always the same: she asks how they like to receive\n  feedback, in writing or out loud, right away or at the end of the week."}
+{"id":"s7","start":618,"end":673,"label":"claim","source":"interview with an engineering manager of eight years","text":"- Her warning: new managers treat silence as a problem."}
+{"id":"s8","start":674,"end":733,"label":"quote","speaker":"the engineering manager interviewed","text":"\"Wait. Count to five. The real answer is\n  the second one.\""}
+{"id":"s9","start":734,"end":812,"label":"claim","source":"interview with an engineering manager of eight years","text":"- She cancels a one-on-one only when the report asks her to, never on her own."}

package/examples/writing/essay/materials/team-survey.md.segments.jsonl

@@ -0,0 +1,6 @@
+{"material":"survey","path":"essay/materials/team-survey.md","sha256":"ae2c821b1731ad02eb3280c28872aa9d2163728b868f262554d0cbfd3da19b97"}
+{"id":"s1","start":0,"end":139,"label":"aside","text":"Summary of an internal survey the author's team ran in the spring, 41 responses, figures checked\nagainst the raw export by a second person."}
+{"id":"s2","start":140,"end":149,"label":"aside","text":"Verified."}
+{"id":"s3","start":151,"end":261,"label":"claim","source":"team survey, spring, 41 responses, figures checked against the raw export","text":"- 29 of 41 said their most useful one-on-one in the last quarter was one where they brought the\n  first topic."}
+{"id":"s4","start":262,"end":358,"label":"claim","source":"team survey, spring, 41 responses, figures checked against the raw export","text":"- 11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status."}
+{"id":"s5","start":359,"end":449,"label":"claim","source":"team survey, spring, 41 responses, figures checked against the raw export","text":"- The most common free-text request, in 9 responses: \"ask me what I want to work on next.\""}

package/examples/writing/essay/materials/voice-memo.md.segments.jsonl

@@ -0,0 +1,7 @@
+{"material":"voice-memo","path":"essay/materials/voice-memo.md","sha256":"c1e07e7d6886f0f3abe638500b614a94883b66f259d272b213f7fe63e70afdc8"}
+{"id":"s1","start":0,"end":87,"label":"aside","text":"Voice memo transcript, recorded by the author on a walk, lightly cleaned. Raw thinking."}
+{"id":"s2","start":89,"end":385,"label":"story","teller":"example-author","text":"My first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a\nlist. I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes\nlater my report said \"cool, thanks\" and left, and I had learned nothing I could not have read in\nthe tracker."}
+{"id":"s3","start":387,"end":572,"label":"claim","own":true,"text":"What I wish someone had told me: the first one-on-one is the only meeting where they get to set\nthe agenda. If you set it, you have told them what the meeting is for, and it is for you."}
+{"id":"s4","start":574,"end":799,"label":"claim","own":true,"text":"The three questions I use now. What is taking more of your energy than it should? What do you\nwant to be doing more of in six months? What should I stop doing, or start doing, that would\nmake your week easier? Then I shut up."}
+{"id":"s5","start":801,"end":897,"label":"stance","text":"Status goes in the tracker. If a one-on-one is a status meeting, cancel it and read the tracker."}
+{"id":"s6","start":899,"end":1037,"label":"aside","text":"Aside, probably not for this piece: my second manager used to walk the one-on-ones outside. I\nliked it but I do not think it is the point."}

package/examples/writing/essay.hyperspec.md

@@ -28,7 +28,7 @@ requirements:
     fails_when: a reader shown only the first two sentences cannot say who should set the agenda
     check:
       rubric: show the simulated reader the first two sentences and ask who sets the agenda; pass only on "the report"
-    source: essay/goldens/opening.md
+    source: dna/essay-new-managers-teach/goldens/opening.md
     author: example-author
   - id: r2
     text: the three questions appear word for word as the voice memo states them
@@ -71,10 +71,10 @@ rejects:
   - any claim about what most managers do that the survey does not support
   - the walking one-on-one aside from the voice memo
 examples:
-  - path: essay/goldens/opening.md
-    why: the claim lands in the first sentence, and the second sentence turns it into an instruction
+  - path: dna/essay-new-managers-teach/goldens/opening.md
+    why: the claim lands in the first sentence, and the two short sentences after it turn it into an instruction
 resume:
-  next_action: mark the three materials into labeled segments, then outline the four spine claims against the form's required parts
+  next_action: outline the four spine claims against the form's required parts, citing the segments each claim points at
 feedback:
   issues: https://github.com/SupersuitUp/hyperspec/issues
   fork: MIT; fork it for your own purposes
@@ -85,40 +85,46 @@ writing:
     items:
       - id: voice-memo
         path: essay/materials/voice-memo.md
+        segments: essay/materials/voice-memo.md.segments.jsonl
         produced_by: example-author
         captured: "2026-09-12"
         how: voice memo, transcribed
         trust: raw
       - id: interview
         path: essay/materials/interview-notes.md
+        segments: essay/materials/interview-notes.md.segments.jsonl
         produced_by: example-author
         captured: "2026-09-15"
         how: notes taken during a call, reviewed by the person interviewed
         trust: considered
       - id: survey
         path: essay/materials/team-survey.md
+        segments: essay/materials/team-survey.md.segments.jsonl
         produced_by: example-author
         captured: "2026-05-30"
         how: survey summary, figures checked against the raw export by a second person
         trust: verified
     check:
-      station: every segment of every material carries a label from the closed set
+      station: every segment of every material carries a label from the closed set, matches its source verbatim, and the markings are current
     source: capture step
     author: agent:claude
   dna:
     writer: example-author
+    scope_dir: dna/essay-new-managers-teach
     scope:
       form: essay
       audience: new managers
       purpose: teach
     rules: style-rules.md
     goldens:
-      - path: essay/goldens/opening.md
-        why: one plain claim, then a second sentence that turns it into something to do
-      - path: essay/goldens/close.md
+      - path: dna/essay-new-managers-teach/goldens/opening.md
+        why: one plain claim in the first sentence, then two short sentences that turn it into something to do
+      - path: dna/essay-new-managers-teach/goldens/status.md
+        why: states what to stop doing, then where that thing already lives, then what the freed half hour is for, one sentence each
+      - path: dna/essay-new-managers-teach/goldens/close.md
         why: ends on an instruction and gives the reason for it in the same sentence
     check:
-      rubric: blind lineup within this scope; a judge shown the generated opening beside the two goldens cannot pick it out
+      rubric: blind lineup within this scope; a judge shown a generated passage beside the scope's three goldens cannot pick it out
     source: goldens marked on the review page
     author: example-author
   persona:
@@ -186,16 +192,16 @@ writing:
     claims:
       - id: c1
         text: the first one-on-one is the one meeting where the report should set the agenda
-        materials: [voice-memo, interview]
+        materials: [voice-memo#s3, interview#s3]
       - id: c2
         text: status belongs in the tracker, and a one-on-one spent on it teaches the manager nothing new
-        materials: [voice-memo, survey]
+        materials: [voice-memo#s2, voice-memo#s5, survey#s4]
       - id: c3
         text: three questions are enough to hand the meeting over
-        materials: [voice-memo]
+        materials: [voice-memo#s4]
       - id: c4
         text: the answer worth having comes after a silence the manager does not fill
-        materials: [interview]
+        materials: [interview#s7, interview#s8]
     check:
       rubric: each claim lands, in order, and the draft argues nothing outside the chain
     source: spine interview
@@ -215,3 +221,8 @@ fiction: false
 A worked example of the writing profile: an essay for new managers, specified before a word of
 it is drafted. Every file this spec names ships beside it. `essay/claims.jsonl` does not exist
 yet, because the claims ledger is written during drafting.
+
+The writer's voice for this piece comes from a scope folder, `dna/essay-new-managers-teach/`:
+the goldens this writer approved for essays that teach new managers, and the features measured
+from them. Another essay by the same writer, for the same readers and the same purpose, would
+point at the same folder.

package/examples/writing/story/materials/bakery-visit.md

@@ -6,3 +6,4 @@ Considered: the owner read these notes and corrected the proofing times.
 - The doors open to customers at 7:00. The first person in is usually a regular.
 - The owner does not talk while shaping. Talking happens at the mixer and at the till.
 - Flour is weighed, never scooped. Water temperature is checked every batch.
+- Said in confidence, not for the story: the lease ends next spring, and she has not told her staff.

package/examples/writing/story/materials/bakery-visit.md.segments.jsonl

@@ -0,0 +1,13 @@
+{"material":"bakery-visit","path":"story/materials/bakery-visit.md","sha256":"5eb09f7c0ad8836378c549392d939f0b070669e972c9e4d94e1f81f27465a19b"}
+{"id":"s1","start":0,"end":90,"label":"aside","text":"Notes from a morning spent at a working bakery, 3:30 to 7:30, with the owner's permission."}
+{"id":"s2","start":91,"end":163,"label":"aside","text":"Considered: the owner read these notes and corrected the proofing times."}
+{"id":"s3","start":165,"end":185,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"- First mix at 3:45."}
+{"id":"s4","start":186,"end":255,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"Rye sourdough proofs about three hours at room temperature in winter."}
+{"id":"s5","start":256,"end":346,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"- Trays are turned halfway through the bake because the back left of a deck oven runs hot."}
+{"id":"s6","start":347,"end":385,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"- The doors open to customers at 7:00."}
+{"id":"s7","start":386,"end":427,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"The first person in is usually a regular."}
+{"id":"s8","start":428,"end":468,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"- The owner does not talk while shaping."}
+{"id":"s9","start":469,"end":514,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"Talking happens at the mixer and at the till."}
+{"id":"s10","start":515,"end":549,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"- Flour is weighed, never scooped."}
+{"id":"s11","start":550,"end":591,"label":"claim","source":"a morning observed at a working bakery, notes corrected by the owner","text":"Water temperature is checked every batch."}
+{"id":"s12","start":592,"end":692,"label":"private","text":"- Said in confidence, not for the story: the lease ends next spring, and she has not told her staff."}

package/examples/writing/story/materials/notes.md

@@ -8,6 +8,8 @@ autumn. Each thinks they are protecting the other.
 The story is four scenes, one morning, 3:40 to 7:00. The oven has a noise. The rye is the thing
 she has never let him do alone.
 
+Open question: does she tell him about the sale before she lets him shape the rye, or after?
+
 What it is about, I think: a craft outlives the room it was practiced in. And: people who love
 each other in a work setting say it through the work.
 

package/examples/writing/story/materials/notes.md.segments.jsonl

@@ -0,0 +1,7 @@
+{"material":"notes","path":"story/materials/notes.md","sha256":"d2af0977ca30dc1f666d219e3c5d2d0f063e91d9d07f14cf703f848ca260ada8"}
+{"id":"s1","start":0,"end":68,"label":"aside","text":"Author's notes for the story, typed over two evenings. Raw thinking."}
+{"id":"s2","start":70,"end":405,"label":"claim","own":true,"text":"A bakery on its last morning before the sale closes. Two people: the owner, who has run it for\nthirty-one years, and the apprentice she took on at sixteen, now nineteen. She has not told him\nit is sold. He has not told her he got into a baking school in another city and leaves in the\nautumn. Each thinks they are protecting the other."}
+{"id":"s3","start":407,"end":534,"label":"claim","own":true,"text":"The story is four scenes, one morning, 3:40 to 7:00. The oven has a noise. The rye is the thing\nshe has never let him do alone."}
+{"id":"s4","start":536,"end":628,"label":"question","text":"Open question: does she tell him about the sale before she lets him shape the rye, or after?"}
+{"id":"s5","start":630,"end":778,"label":"stance","text":"What it is about, I think: a craft outlives the room it was practiced in. And: people who love\neach other in a work setting say it through the work."}
+{"id":"s6","start":780,"end":838,"label":"stance","text":"The last line should be about bread, never about feelings."}

package/examples/writing/story/materials/scene-list.md.segments.jsonl

@@ -0,0 +1,14 @@
+{"material":"scene-list","path":"story/materials/scene-list.md","sha256":"8181cdb35cd1afad01809367de15b3233f24fc7bede5b7b89c022f05e3d655e0"}
+{"id":"s1","start":0,"end":51,"label":"aside","text":"Scene list, agreed with the editor before drafting."}
+{"id":"s2","start":52,"end":63,"label":"aside","text":"Considered."}
+{"id":"s3","start":65,"end":95,"label":"claim","own":true,"text":"- scene-1, 3:40: Theo arrives."}
+{"id":"s4","start":96,"end":119,"label":"claim","own":true,"text":"Ines is already mixing."}
+{"id":"s5","start":120,"end":135,"label":"claim","own":true,"text":"The oven noise."}
+{"id":"s6","start":136,"end":162,"label":"claim","own":true,"text":"No one says anything real."}
+{"id":"s7","start":163,"end":188,"label":"claim","own":true,"text":"- scene-2, 4:30: shaping."}
+{"id":"s8","start":189,"end":259,"label":"claim","own":true,"text":"Ines lets Theo shape the rye for the first time, and does not say why."}
+{"id":"s9","start":260,"end":286,"label":"claim","own":true,"text":"- scene-3, 5:50: the bake."}
+{"id":"s10","start":287,"end":344,"label":"claim","own":true,"text":"Ines tells Theo the bakery is sold, while turning a tray."}
+{"id":"s11","start":345,"end":384,"label":"claim","own":true,"text":"- scene-4, 6:55: before the doors open."}
+{"id":"s12","start":385,"end":418,"label":"claim","own":true,"text":"Theo tells Ines about the school."}
+{"id":"s13","start":419,"end":451,"label":"claim","own":true,"text":"She hands him the\n  starter jar."}

package/examples/writing/story.hyperspec.md

@@ -74,7 +74,7 @@ examples:
   - path: story/goldens/dialogue.md
     why: three short lines carry a ritual both characters know, without either of them naming it
 resume:
-  next_action: mark the three materials into labeled segments, then draft scene-1 from the scene list with Theo's knowledge as of scene-1
+  next_action: draft scene-1 from the scene list with Theo's knowledge as of scene-1
 feedback:
   issues: https://github.com/SupersuitUp/hyperspec/issues
   fork: MIT; fork it for your own purposes
@@ -85,24 +85,27 @@ writing:
     items:
       - id: notes
         path: story/materials/notes.md
+        segments: story/materials/notes.md.segments.jsonl
         produced_by: example-author
         captured: "2026-08-20"
         how: typed notes
         trust: raw
       - id: bakery-visit
         path: story/materials/bakery-visit.md
+        segments: story/materials/bakery-visit.md.segments.jsonl
         produced_by: example-author
         captured: "2026-08-28"
         how: notes taken on site, corrected by the bakery owner afterwards
         trust: considered
       - id: scene-list
         path: story/materials/scene-list.md
+        segments: story/materials/scene-list.md.segments.jsonl
         produced_by: example-author
         captured: "2026-09-02"
         how: scene list agreed with the editor
         trust: considered
     check:
-      station: every segment of every material carries a label from the closed set
+      station: every segment of every material carries a label from the closed set, matches its source verbatim, and the markings are current
     source: capture step
     author: agent:claude
   dna:
@@ -184,13 +187,13 @@ writing:
     claims:
       - id: c1
         text: each of them hides their news to protect the other, and the hiding is the thing they share
-        materials: [notes, scene-list]
+        materials: [notes#s2, scene-list#s10, scene-list#s12]
       - id: c2
         text: people who love each other at work say it through the work
-        materials: [notes, bakery-visit]
+        materials: [notes#s5, bakery-visit#s8, scene-list#s8]
       - id: c3
         text: a craft outlives the room it was practiced in
-        materials: [notes, scene-list]
+        materials: [notes#s5, scene-list#s13]
     check:
       rubric: each claim lands, in order, through what the characters do, and the story argues nothing outside the chain
     source: spine interview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/hyperspec",
-  "version": "0.3.0",
+  "version": "0.5.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": {
@@ -8,6 +8,7 @@
   },
   "exports": {
     "./recipe": "./src/writer.mjs",
+    "./writing": "./src/writing-exports.mjs",
     "./package.json": "./package.json"
   },
   "files": [

package/src/blobs.mjs

@@ -41,7 +41,7 @@ export function blobPath(root, hex) {
 // Atomic: bytes land in a temp file in the same directory first, then a single renameSync
 // (atomic on one filesystem) puts them at the final path. A process killed mid-write leaves
 // only the orphaned temp file, never a partially-written file sitting at the content-addressed
-// path — the failure mode a plain writeFileSync(path, bytes) would otherwise leave behind, and
+// path. That is the failure mode a plain writeFileSync(path, bytes) would otherwise leave behind, and
 // which nothing short of an explicit verifyBlob would ever catch afterward.
 export function putBlob(root, bytes) {
   const hex = sha256(bytes);

package/src/compare.mjs

@@ -66,7 +66,7 @@ export function compare(childRecipePath, { doctor, parent: parentOption, spec: s
   const specHash = sha256(readFileSync(specAbs));
   // specChanged is about the PARENT's record, not the child's: it tells the caller the spec being
   // graded against now differs from what the parent was made under. Both outputs still get graded
-  // against this one spec file either way — never each against its own.
+  // against this one spec file either way, never each against its own.
   const specChanged = parentRecipe.spec?.sha256 !== specHash;
   if (specChanged) warnings.push("spec changed since the parent was made; both outputs graded against the current file");
 
@@ -114,14 +114,14 @@ export function compare(childRecipePath, { doctor, parent: parentOption, spec: s
       const ledgerAbs = resolve(specDir, ledgerDecl);
       const ledgerDir = dirname(ledgerAbs);
       // The child's own `change` is null whenever it has no genealogical parent of its own (a root
-      // recipe compared against an explicit, unrelated --parent — compare's usage check allows
+      // recipe compared against an explicit, unrelated --parent; compare's usage check allows
       // this: it only requires *either* the child's recorded parent.path *or* an explicit
       // override). Fall back to naming what was actually compared against, so `change` and the
-      // not-improved `reason` below are never "after null" — both a broken persisted record and,
+      // not-improved `reason` below are never "after null", which would be both a broken persisted record and,
       // for the "improved" verdict, a lint failure (rules.mjs's verdict-change: `!str(v.change)`).
       const childChange = child.change ?? `compared against ${relative(ledgerDir, parentRecipeAbs)}`;
       // A compare line must satisfy test 9 ("it improves itself"), which only knows the
-      // verdict vocabulary one-shot/improved/not-improved — never a new "compare" verdict. A
+      // verdict vocabulary one-shot/improved/not-improved, never a new "compare" verdict. A
       // strictly higher child score is improved (and already carries change, which doubles as
       // that verdict's required field). Equal or lower is not-improved, with a reason a later
       // session can argue with; when it's a genuine regression (strictly lower, not merely tied)
@@ -162,8 +162,8 @@ export function compare(childRecipePath, { doctor, parent: parentOption, spec: s
 
 // Runs the doctor command once, via /bin/sh -c, over one output against the one spec. stdin is
 // { output, spec } (absolute paths); the last non-empty stdout line must be JSON with a numeric
-// score. Nothing recipe-derived is ever interpolated into the command string — only passed on
-// stdin — so the same command string is reused verbatim for the parent and the child.
+// score. Nothing recipe-derived is ever interpolated into the command string; it is only passed on
+// stdin, so the same command string is reused verbatim for the parent and the child.
 function runDoctor(doctorCmd, outputAbs, specAbs) {
   const res = spawnSync("/bin/sh", ["-c", doctorCmd], {
     input: JSON.stringify({ output: outputAbs, spec: specAbs }),