@supersuit/hyperspec 0.3.0 → 0.4.0

package/examples/writing/essay.hyperspec.md

@@ -74,7 +74,7 @@ examples:
   - path: essay/goldens/opening.md
     why: the claim lands in the first sentence, and the second sentence turns 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,24 +85,27 @@ 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:
@@ -186,16 +189,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

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.4.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 }),

package/src/fsutil.mjs

@@ -2,7 +2,7 @@ import { renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { relative, resolve, sep } from "node:path";
 
-// True when `target`, resolved against `dir`, stays inside `dir` — refuses a `..`-escape and an
+// True when `target`, resolved against `dir`, stays inside `dir`. It refuses a `..`-escape and an
 // absolute path pointing elsewhere. Both a relative `target` (including one that climbs out via
 // `../`) and an already-absolute `target` are handled the same way, since `path.resolve(dir,
 // target)` already treats an absolute second argument as overriding the first: either way, the

package/src/labels.mjs

@@ -0,0 +1,6 @@
+// The closed vocabulary every segment of a marked material is labeled from (hyperspec 0.4). It lives in
+// this leaf module, which imports nothing, so src/segments.mjs can read it without importing
+// src/writing.mjs: writing.mjs imports writing-fields.mjs, which imports segments.mjs, and reading
+// the labels through writing.mjs made that a cycle. writing.mjs re-exports it for callers that
+// already import it from there.
+export const MATERIAL_LABELS = Object.freeze(["claim", "story", "quote", "stance", "question", "aside", "private"]);

package/src/reproduce.mjs

@@ -11,7 +11,7 @@ const MALFORMED = "recorded hash is not a SHA-256 hash (64 lowercase hex charact
 const blobWhy = (hex, why) => (present(hex) && !isSha256(hex) ? MALFORMED : why);
 
 // Spec requirement `reproduce`: replay the record and hash-check it. Never invokes a model,
-// never runs a command, never regenerates a byte of content — every blob this looks at already
+// never runs a command, never regenerates a byte of content. Every blob this looks at already
 // exists in the store, and this only confirms the recipe's own claims about it still hold.
 //
 // Checks, in order (and every one is reported, nothing stops the walk early): every input blob
@@ -98,8 +98,8 @@ export function reproduce(recipePath, { store, restore = false } = {}) {
   // 5. The output file on disk, if present, hashes to output.sha256. Absent is vacuously fine:
   // reproduce doesn't require the file to already exist, only that it agrees when it does.
   //
-  // The recipe is a plain JSON file on disk — exactly the kind of claim reproduce exists to
-  // distrust — so output.path is never trusted blind. A hand-edited or corrupted recipe could
+  // The recipe is a plain JSON file on disk, exactly the kind of claim reproduce exists to
+  // distrust, so output.path is never trusted blind. A hand-edited or corrupted recipe could
   // name a path outside the recipe's own directory (a `../` climb, or an absolute path); refuse
   // before touching disk at all, rather than reading from or (worse, under --restore) writing to
   // wherever it points.
@@ -120,12 +120,12 @@ export function reproduce(recipePath, { store, restore = false } = {}) {
       }
 
       // restore: true writes the output file from its blob, but only when the output blob
-      // itself verified (step 4) — restoring from an unverified blob would just write
+      // itself verified (step 4); restoring from an unverified blob would just write
       // different wrong bytes. Covers both a lost file (never existed / deleted) and an
       // edited one. The write is atomic (temp file + rename, same pattern as putBlob), so a
       // crash mid-write never leaves the file in a state that is neither the old nor the new
       // content, and a write failure is caught and reported as a failing step rather than
-      // thrown out of reproduce() — this function always returns a structured result.
+      // thrown out of reproduce(): this function always returns a structured result.
       const needsRestore = !fileExists || !matches;
       if (restore && needsRestore && outputBlobOk) {
         const blob = getBlob(root, outputSha);