@supersuit/hyperspec 0.7.0 → 0.8.0

package/examples/writing/course.hyperspec.md

@@ -0,0 +1,205 @@
+---
+hyperspec: "0.1"
+title: "Bread from zero: a four-lesson course"
+kind: course
+profile: writing
+decisions:
+  - id: kind
+    state: decided
+    value: a course of four lessons in two parts, for someone who has never baked a loaf
+    source: course/materials/brief.md
+    author: example-author
+    chosen_by: human
+  - id: lesson-shape
+    state: decided
+    value: every lesson opens with what the reader can do after it and the terms it defines, and ends with one thing to do in a kitchen
+    source: course/materials/brief.md, the paragraph on ending each lesson
+    author: example-author
+    chosen_by: human
+  - id: part-files
+    state: delegated
+    rule: one file per part, named part-<n>.md, so a new part is picked up by the files pattern without editing the spec
+    source: course layout
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: no lesson uses a term before the lesson that defines it
+    fails_when: the sequence station reports a term used before it is defined
+    check:
+      station: sequence station, order guard
+    source: course/materials/brief.md
+    author: example-author
+  - id: r2
+    text: every term is defined in exactly one lesson
+    fails_when: the sequence station reports a term defined twice
+    check:
+      station: sequence station, defined-once guard
+    source: lesson-shape decision
+    author: example-author
+  - id: r3
+    text: every lesson carries its three sections
+    fails_when: a lesson has no "After this lesson you can", "New terms" or "Try this" section
+    check:
+      station: sequence station, sections guard
+    source: lesson-shape decision
+    author: example-author
+  - id: r4
+    text: each lesson defines the terms the outline promises for it
+    fails_when: the outline promises a term in a lesson that does not define it
+    check:
+      station: sequence station, outline guard
+    source: course/outline.md
+    author: example-author
+  - id: r5
+    text: every Try this can be done in a home kitchen in one day, apart from the starter, which takes a week
+    fails_when: a Try this needs equipment beyond a bowl, a scale, a jar, an oven and a heavy pot
+    check:
+      rubric: list what each Try this needs; fail on anything outside that list
+    source: course/materials/brief.md
+    author: example-author
+rejects:
+  - a recipe before the reader has the words to follow it
+  - a term used before the lesson that defines it
+examples:
+  - path: course/goldens/lesson.md
+    why: an instruction, then the reader's likely worry named plainly, then what to do next
+resume:
+  next_action: bake the course's two loaves from Lesson 3 and photograph their crumb for Lesson 4
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: course/runs.jsonl
+writing:
+  materials:
+    items:
+      - id: brief
+        path: course/materials/brief.md
+        segments: course/materials/brief.md.segments.jsonl
+        produced_by: example-author
+        captured: "2026-09-20"
+        how: written after teaching the class twice
+        trust: considered
+    check:
+      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:
+      form: course
+      audience: first-time bakers
+      purpose: teach
+    rules: style-rules.md
+    goldens:
+      - path: course/goldens/lesson.md
+        why: an instruction, then the reader's likely worry named plainly, then what to do next
+    check:
+      rubric: blind lineup within this scope
+    source: goldens marked on the review page
+    author: example-author
+  persona:
+    identity: self
+    stance: guide
+    may_assert:
+      - what the author saw go wrong when teaching the class
+    will_not_say:
+      - a bake time or temperature for an oven the author has not used
+    facts_from: sources
+    check:
+      rubric: persona-consistency judge
+    source: persona interview
+    author: example-author
+  audience:
+    who: someone who has never baked a loaf of bread
+    funnel_now: has bought flour and has never used it for bread
+    knows:
+      - flour
+      - oven
+    believes_now: bread takes a recipe and a lot of skill
+    wants: to bake one good loaf
+    reads_on: a tablet propped up in the kitchen
+    reader: person
+    check:
+      station: the sequence station defines every term before it is used
+      rubric: simulated reader reports where it got lost
+    source: audience interview
+    author: example-author
+  goal:
+    from: has never baked bread
+    to: bakes a loaf and reads its crumb
+    next_if_worked: starts a starter the day they finish Lesson 2
+    change:
+      kind: action
+      text: the reader bakes their first loaf
+    conditions: [r1, r2, r3, r4, r5]
+    check:
+      rubric: the doctor grades the course against every condition
+    source: goal interview
+    author: example-author
+  form:
+    name: course
+    length:
+      min: 400
+      max: 1500
+      unit: words
+    required_parts:
+      - "Part 1: Dough"
+      - "Part 2: The bake"
+    stations:
+      - the sequence station
+    sequence:
+      unit: Lesson
+      files:
+        - course/part-*.md
+      sections:
+        - After this lesson you can
+        - New terms
+        - Try this
+      terms_section: New terms
+      outline: course/outline.md
+      teaser: Next,
+    check:
+      station: structure and length, then the sequence station
+    source: form decision
+    author: example-author
+  spine:
+    kind: primer
+    claims:
+      - id: c1
+        text: a first-time baker needs four words before any recipe
+        materials: [brief#s2]
+      - id: c2
+        text: the order is water and flour, then the rise, then shaping, then the oven
+        materials: [brief#s3]
+      - id: c3
+        text: each lesson ends with something to do in a real kitchen
+        materials: [brief#s4, brief#s5]
+    check:
+      rubric: each claim lands, in order
+    source: spine interview
+    author: example-author
+  sources:
+    ledger: course/claims.jsonl
+    unsourced_claim: fail
+    check:
+      station: every factual claim in the ledger points at a source span
+    source: sourcing pass
+    author: agent:claude
+fiction: false
+---
+
+# Bread from zero
+
+A worked example of a sequential work: a course of four lessons in two parts, one file per part.
+The spec lists the parts as `course/part-*.md`, so `check` needs no `--draft`: the parts, joined
+in order, are the draft.
+
+```bash
+npx @supersuit/hyperspec check course.hyperspec.md
+```
+
+The `sequence` station holds the course to what a reader of Lesson 3 depends on: Lessons 1 and 2
+defined every word it uses. The outline in `course/outline.md` promises the terms each lesson
+defines, and the station checks the lessons keep that promise.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/hyperspec",
-  "version": "0.7.0",
+  "version": "0.8.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/check.mjs

@@ -21,6 +21,7 @@ import { readDraft } from "./draft.mjs";
 import { openLedger, priorLines, ledgerDraftKey, ledgerVerdict } from "./ledger.mjs";
 import { STATIONS, STATION_NAMES } from "./stations/index.mjs";
 import { str } from "./placeholder.mjs";
+import { readSequenceDraft, sequenceFilesDecl, sourceAt } from "./sequence-draft.mjs";
 
 const present = (v) => typeof v === "string" && v.trim().length > 0;
 
@@ -95,17 +96,29 @@ export function lintBlock(spec, specPathArg) {
   };
 }
 
+// A finding from a draft assembled out of a sequence's files names the file and its own line in
+// it, rather than a line of the joined text nobody can open.
+function locate(finding, draft) {
+  const src = typeof finding.line === "number" ? sourceAt(draft, finding.line) : null;
+  return src ? { ...finding, file: src.file, line: finding.line - src.startLine + 1 } : finding;
+}
+
 // runCheck(specPathArg, draftPathArg, { only }): specPathArg and draftPathArg are exactly what
 // the CLI (or a caller) was given, never resolved, so every path this returns or writes to the
 // ledger is displayed and recorded the way the operator typed it, not as an absolute path on this
 // machine. only, when given, is an array of station names to run instead of every registered one.
+//
+// With no draftPathArg, a spec that lists writing.form.sequence.files is checked against those
+// files, joined in reading order (src/sequence-draft.mjs); any other spec still needs --draft.
 export function runCheck(specPathArg, draftPathArg, { only } = {}) {
   if (!present(specPathArg)) return { usage: true, error: "check needs a spec path" };
-  if (!present(draftPathArg)) return { usage: true, error: "check needs --draft <file>" };
+  const needsDraft = { usage: true, error: "check needs --draft <file>" };
 
   const loaded = loadWritingSpec(specPathArg, "check");
+  if (!present(draftPathArg) && (loaded.usage || !sequenceFilesDecl(loaded.spec).length)) return needsDraft;
   if (loaded.usage) return loaded;
   const { spec } = loaded;
+  const fromSequence = !present(draftPathArg);
 
   // --only: every name must be one this build's registry knows; unknown names are a usage error
   // (exit 2) rather than a silent no-op, and the run order always follows the registry, never the
@@ -123,12 +136,16 @@ export function runCheck(specPathArg, draftPathArg, { only } = {}) {
   const blocked = lintBlock(spec, specPathArg);
   if (blocked) return blocked;
 
-  // BOM stripped, CRLF-clean lines, sha256 over the raw bytes: see src/draft.mjs.
-  const draft = readDraft(draftPathArg);
-  if (!draft) return { usage: true, error: `cannot read draft: ${draftPathArg}` };
+  // BOM stripped, CRLF-clean lines, sha256 over the raw bytes: see src/draft.mjs. A sequence's
+  // draft is its files joined; its ledger key is the files entry as the spec writes it, so the
+  // history of the work stays one history as parts are added.
+  const draft = fromSequence ? readSequenceDraft(spec, specPathArg) : readDraft(draftPathArg);
+  const draftLabel = fromSequence ? sequenceFilesDecl(spec).join(", ") : draftPathArg;
+  if (!draft) return { usage: true, error: fromSequence ? `writing.form.sequence.files matches no file: ${draftLabel}` : `cannot read draft: ${draftPathArg}` };
 
   const ctx = {};
-  const results = stationsToRun.map((s) => runStation(s, spec, draft, ctx));
+  const results = stationsToRun.map((s) => runStation(s, spec, draft, ctx))
+    .map((r) => (draft.sources ? { ...r, findings: r.findings.map((f) => locate(f, draft)) } : r));
   const failing = results.filter((r) => r.status === "fail").map((r) => r.station);
   const code = failing.length ? 1 : 0;
 
@@ -146,7 +163,7 @@ export function runCheck(specPathArg, draftPathArg, { only } = {}) {
   const ledger = openLedger(spec);
   if (ledger?.warning) ledgerWarning = ledger.warning;
   else if (ledger) {
-    const draftKey = ledgerDraftKey(spec.dir, draftPathArg);
+    const draftKey = fromSequence ? draftLabel : ledgerDraftKey(spec.dir, draftPathArg);
     const specSha = sha256(readFileSync(resolve(specPathArg)));
     const statusNow = Object.fromEntries(results.map((r) => [r.station, r.status]));
 
@@ -177,7 +194,8 @@ export function runCheck(specPathArg, draftPathArg, { only } = {}) {
   return {
     ok: true,
     specPath: specPathArg,
-    draftPath: draftPathArg,
+    draftPath: draftLabel,
+    ...(fromSequence ? { files: draft.sources.map((x) => x.file) } : {}),
     draftSha256: draft.sha256,
     stations: results,
     failing,

package/src/sequence-draft.mjs

@@ -0,0 +1,75 @@
+// A work read in order often lives in several files (one per part, one per lesson). When a writing
+// spec lists them as writing.form.sequence.files, `hyperspec check <spec>` needs no --draft: the
+// draft is those files, joined in order. This module owns which files that is and how they join, so
+// lint (every entry must match a file) and check (the draft) agree on one reading.
+
+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";
+
+const list = (v) => (Array.isArray(v) ? v : []);
+const byNumber = (a, b) => a.localeCompare(b, "en", { numeric: true });
+
+// The declared entries, as written: writing.form.sequence.files, strings only.
+export function sequenceFilesDecl(spec) {
+  return list(spec?.data?.writing?.form?.sequence?.files).map(str).filter(Boolean);
+}
+
+// The files one entry names, relative to the spec's folder and written with "/": the entry itself
+// when it has no "*", or every file in its folder whose name matches, sorted so part-2 comes before
+// part-10. A "*" matches within a file name only; the folder part is taken literally. [] when
+// nothing matches.
+export function expandEntry(specDir, entry) {
+  const clean = entry.replace(/\\/g, "/");
+  const dir = posix.dirname(clean);
+  const base = posix.basename(clean);
+  const isFile = (rel) => { try { return statSync(resolve(specDir, rel)).isFile(); } catch { return false; } };
+  if (!base.includes("*")) return isFile(clean) ? [clean] : [];
+  const re = new RegExp(`^${base.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")}$`);
+  let names = [];
+  try { names = readdirSync(resolve(specDir, dir)); } catch { return []; }
+  return names.filter((n) => re.test(n)).sort(byNumber).map((n) => (dir === "." ? n : `${dir}/${n}`)).filter(isFile);
+}
+
+// Every file of the sequence in reading order, each once (at its first position).
+export function sequenceFiles(specDir, entries) {
+  const out = [];
+  for (const e of entries) for (const f of expandEntry(specDir, e)) if (!out.includes(f)) out.push(f);
+  return out;
+}
+
+// The draft `check` grades when the spec lists sequence files and no --draft is given:
+// { 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
+// 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));
+  if (!files.length) return null;
+  const parts = [];
+  const hashed = [];
+  const sources = [];
+  let startLine = 1;
+  for (const file of files) {
+    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, ""));
+    if (!text.endsWith("\n")) text += "\n";
+    const lineCount = text.split("\n").length - 1;
+    sources.push({ file, at: join(dirname(specPathArg), file), startLine, lineCount });
+    parts.push(text);
+    startLine += lineCount;
+  }
+  const text = parts.join("");
+  return { path: sources[0].at, text, lines: splitLines(text), sha256: sha256(Buffer.concat(hashed)), sources };
+}
+
+// The source holding 1-based draft line `line`, or null.
+export function sourceAt(draft, line) {
+  return list(draft?.sources).find((s) => line >= s.startLine && line < s.startLine + s.lineCount) ?? null;
+}

package/src/stations/index.mjs

@@ -3,7 +3,7 @@
 // src/check.mjs calls; adding a station is adding one file plus one line here, which is the whole
 // point of the registry existing rather than check.mjs importing each station by name itself.
 //
-// The order: form, terms, claims, quotes, private, dna, links. quotes and private share ctx (util.mjs's
+// The order: form, terms, claims, quotes, private, dna, links, sequence. quotes and private share ctx (util.mjs's
 // markedSegments caches the spec's marked materials there), so a check run reads them once.
 
 import * as form from "./form.mjs";
@@ -13,6 +13,7 @@ import * as quotes from "./quotes.mjs";
 import * as privateStation from "./private.mjs";
 import * as dna from "./dna.mjs";
 import * as links from "./links.mjs";
+import * as sequence from "./sequence.mjs";
 
 export const STATIONS = Object.freeze([
   { name: form.name, run: form.run },
@@ -22,6 +23,7 @@ export const STATIONS = Object.freeze([
   { name: privateStation.name, run: privateStation.run },
   { name: dna.name, run: dna.run },
   { name: links.name, run: links.run },
+  { name: sequence.name, run: sequence.run },
 ]);
 
 export const STATION_NAMES = Object.freeze(STATIONS.map((s) => s.name));

package/src/stations/links.mjs

@@ -30,6 +30,7 @@
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { lineAt, maskCode, maskRanges, truncate } from "./util.mjs";
+import { sourceAt } from "../sequence-draft.mjs";
 
 export const name = "links";
 
@@ -226,6 +227,12 @@ function undefinedReferenceFinding(label, line) {
 
 export function run(spec, draft) {
   const draftDirAbs = dirname(resolve(draft.path));
+  // A draft assembled from a sequence's files (src/sequence-draft.mjs) resolves each relative link
+  // beside the file that holds it.
+  const dirAt = (line) => {
+    const src = sourceAt(draft, line);
+    return src ? dirname(resolve(src.at)) : draftDirAbs;
+  };
 
   // Masking pipeline: code first, then each link form in turn, each pass working on the text the
   // previous pass left behind, so nothing is ever matched twice by a later, looser pattern (a
@@ -253,8 +260,9 @@ export function run(spec, draft) {
   const entries = [];
 
   for (const { start, url } of [...mdLinks, ...bare]) {
-    const reason = checkUrl(url, draftDirAbs);
-    if (reason) entries.push({ start, finding: reasonFinding(reason, url, lineAt(draft.text, start)) });
+    const line = lineAt(draft.text, start);
+    const reason = checkUrl(url, dirAt(line));
+    if (reason) entries.push({ start, finding: reasonFinding(reason, url, line) });
   }
 
   for (const { start, label } of [...fullRefs, ...shortcutRefs]) {
@@ -264,7 +272,7 @@ export function run(spec, draft) {
       entries.push({ start, finding: undefinedReferenceFinding(label, line) });
       continue;
     }
-    const reason = checkUrl(def.url, draftDirAbs);
+    const reason = checkUrl(def.url, dirAt(line));
     if (reason) entries.push({ start, finding: reasonFinding(reason, def.url, line) });
   }