@supersuit/hyperspec 0.2.0 → 0.3.0

package/examples/writing/story.hyperspec.md

@@ -0,0 +1,285 @@
+---
+hyperspec: "0.1"
+title: The Rye
+kind: short story
+profile: writing
+decisions:
+  - id: point-of-view
+    state: decided
+    value: first person, told by Theo, in the past tense
+    source: story/materials/notes.md
+    author: example-author
+    chosen_by: human
+  - id: time-span
+    state: decided
+    value: one morning, 3:40 to 7:00, in the four scenes of the scene list and in that order
+    source: story/materials/scene-list.md
+    author: example-author
+    chosen_by: human
+  - id: bakery-name
+    state: delegated
+    rule: the bakery is never named; it is always "the bakery" or "Ines's"
+    source: editor's note on the scene list
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: the two voices cannot be confused
+    fails_when: a judge shown ten lines of dialogue with the speaker hidden names the wrong speaker for more than one of them
+    check:
+      rubric: blind attribution test across both characters, ten lines drawn at random from the draft
+    source: story/materials/notes.md
+    author: example-author
+  - id: r2
+    text: no one says what they could not know yet
+    fails_when: Theo mentions the sale before scene-3, or Ines mentions the school before scene-4
+    check:
+      station: knowledge-leak check of every line against each character's knowledge timeline
+    source: story/materials/scene-list.md
+    author: example-author
+  - id: r3
+    text: the bakery's process matches a real working morning
+    fails_when: a proofing time, the tray turn, or the opening time differs from story/materials/bakery-visit.md
+    check:
+      station: every process detail in the claims ledger points at a span of the bakery visit notes
+    source: story/materials/bakery-visit.md
+    author: agent:claude
+  - id: r4
+    text: the story is the four scenes of the scene list, in order
+    fails_when: the draft has more or fewer than four scenes, or they run out of the scene list's order
+    check:
+      station: structure check against story/materials/scene-list.md
+    source: story/materials/scene-list.md
+    author: example-author
+  - id: r5
+    text: the last line is about bread
+    fails_when: the final sentence names a feeling, or does not mention bread, dough, flour or the starter
+    check:
+      rubric: read the final sentence; fail if it names an emotion or mentions none of bread, dough, flour or the starter
+    source: story/materials/notes.md
+    author: example-author
+  - id: r6
+    text: the story stays inside its length envelope
+    fails_when: the word count is under 2,500 or over 4,000
+    check:
+      station: word count against form.length
+    source: editor's brief
+    author: example-author
+rejects:
+  - either character saying out loud that they love or will miss the other
+  - a flashback outside the one morning
+  - a scene where the oven noise is explained
+  - an ending that tells the reader what the starter jar means
+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
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: story/runs.jsonl
+writing:
+  materials:
+    items:
+      - id: notes
+        path: story/materials/notes.md
+        produced_by: example-author
+        captured: "2026-08-20"
+        how: typed notes
+        trust: raw
+      - id: bakery-visit
+        path: story/materials/bakery-visit.md
+        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
+        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
+    source: capture step
+    author: agent:claude
+  dna:
+    writer: example-author
+    scope:
+      form: short story
+      audience: literary magazine readers
+      purpose: move
+    rules: style-rules.md
+    goldens:
+      - path: story/goldens/opening.md
+        why: the narrator's voice arrives through one concrete sound, and the sentence about the mixer tells you how he sees the world
+      - path: story/goldens/dialogue.md
+        why: the narration between lines says only what Theo notices, never what Ines feels
+    check:
+      rubric: blind lineup within this scope; a judge shown a generated passage beside the two goldens cannot pick it out
+    source: goldens marked on the review page
+    author: example-author
+  persona:
+    identity: character:theo
+    stance: witness
+    may_assert:
+      - what Theo sees, hears and does in the bakery that morning
+      - what Theo knows as of the current scene, per his knowledge timeline
+    will_not_say:
+      - what Ines is thinking or feeling
+      - anything Theo does not know yet at that point in the morning
+    facts_from: sources
+    check:
+      rubric: persona-consistency judge; Theo's narration stays a witness's, and no process detail appears that is not in the claims ledger
+    source: persona interview
+    author: example-author
+  audience:
+    who: readers of a quarterly literary magazine who read short fiction in print
+    funnel_now: has turned to the story in the magazine without knowing the author
+    knows:
+      - bakery
+      - apprentice
+      - sourdough
+    believes_now: nothing yet about this author or these two people
+    wants: a story they can finish in one sitting and keep thinking about
+    reads_on: print, in one sitting of about fifteen minutes
+    reader: person
+    check:
+      station: term check against knows; proof, starter and deck oven are made plain by context on first use
+      rubric: simulated reader reports where it got lost and where it stopped reading
+    source: editor's brief
+    author: example-author
+  goal:
+    from: has never read the author
+    to: finishes the story and remembers the starter jar
+    next_if_worked: looks for the author's other stories
+    change:
+      kind: feeling
+      text: the reader feels the handover of the starter jar as the moment the two say what neither says aloud
+    conditions: [r1, r2, r3, r4, r5, r6]
+    check:
+      rubric: the doctor grades the draft against every condition; the simulated reader is asked what the starter jar meant and whether it would look for the author's next story
+    source: goal interview
+    author: example-author
+  form:
+    name: short story
+    length:
+      min: 2500
+      max: 4000
+      unit: words
+    required_parts:
+      - four scenes, in the scene list's order
+      - a last line about bread
+    stations:
+      - continuity against the scene list
+      - knowledge-leak check, per character, per scene
+    check:
+      station: structure and length check against required_parts and length
+    source: editor's brief
+    author: example-author
+  spine:
+    kind: story
+    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]
+      - id: c2
+        text: people who love each other at work say it through the work
+        materials: [notes, bakery-visit]
+      - id: c3
+        text: a craft outlives the room it was practiced in
+        materials: [notes, scene-list]
+    check:
+      rubric: each claim lands, in order, through what the characters do, and the story argues nothing outside the chain
+    source: spine interview
+    author: example-author
+  sources:
+    ledger: story/claims.jsonl
+    unsourced_claim: fail
+    check:
+      station: every process detail in the ledger points at a source span; every quote matches its source verbatim
+    source: sourcing pass
+    author: agent:claude
+  characters:
+    - id: ines
+      speech:
+        uses:
+          - instructions in the imperative
+          - numbers, weights and times
+          - first names, for customers
+        never:
+          - an apology in words
+          - a sentence about her own feelings
+          - a question she does not need answered
+        rhythm: short, flat sentences, often without a subject; silence where another person would reassure
+      wants: to leave the bakery in hands she trusts, without having to say that she is leaving it
+      fears: that Theo will stay in a trade with no bakery to do it in, because of her
+      hides: that she sold the bakery two weeks ago
+      knowledge:
+        - by: scene-1
+          knows: the sale closes on Friday, and the new owners will not keep it a bakery
+        - by: scene-4
+          knows: Theo has a place at a baking school in another city and leaves in the autumn
+      relationships:
+        - to: theo
+          how: gives him instructions where another person would give praise
+        - to: customers
+          how: warm and unhurried, asks after their families by name
+      arc_state: has let go of the bakery, and has not yet let go of Theo
+      golden_lines:
+        - Flour first. Then you can talk.
+        - Left side runs hot. Turn them at eight minutes.
+        - Sold means sold. Shape the rye.
+      rejected_lines:
+        - I'm so sorry I didn't tell you sooner, Theo.
+        - This place has been my whole life, you know?
+        - Would you like to try the rye today?
+      check:
+        rubric: blind attribution test, knowledge-leak check against the timeline, consistency against golden and rejected lines
+      source: story/materials/notes.md
+      author: example-author
+    - id: theo
+      speech:
+        uses:
+          - questions he already knows the answer to
+          - hedges such as "I mean" and "kind of"
+          - a joke when he is nervous
+        never:
+          - a flat instruction
+          - a word of baking jargon he has not heard Ines use first
+        rhythm: long sentences that double back on themselves and end in a question
+      wants: Ines to tell him he is ready, in words, once
+      fears: that leaving for school is a betrayal of the person who taught him
+      hides: that he has a place at a baking school in another city and leaves in the autumn
+      knowledge:
+        - by: scene-1
+          knows: the oven has made the noise since March, and he leaves for school in the autumn
+        - by: scene-3
+          knows: the bakery is sold, and the new owners will not keep it a bakery
+      relationships:
+        - to: ines
+          how: asks questions to keep her talking, and never interrupts her while she shapes
+      arc_state: still acting the apprentice while privately already leaving
+      golden_lines:
+        - Okay but like, if the oven's made that noise since March, is it a noise, or is that just how the oven talks now?
+        - I can do the rye. I mean, I think I can do the rye. I did it Tuesday, kind of.
+        - So is that a yes, or is that the face you make when it's a yes?
+      rejected_lines:
+        - Shape the rye.
+        - I have been accepted to a culinary program and will be leaving in the autumn.
+        - Left side runs hot, turn them early.
+      check:
+        rubric: blind attribution test, knowledge-leak check against the timeline, consistency against golden and rejected lines
+      source: story/materials/notes.md
+      author: example-author
+fiction: true
+---
+
+# The Rye
+
+A worked example of the writing profile for fiction: a short story with two characters, each
+specified well enough that an agent can write their dialogue and a judge can tell them apart.
+Every file this spec names ships beside it. `story/claims.jsonl` does not exist yet, because the
+claims ledger is written during drafting.

package/examples/writing/style-rules.md

@@ -0,0 +1,19 @@
+# Style rules
+
+The always-on layer. These apply to everything this writer publishes, whatever the form, the
+audience or the purpose. Goldens change with the scope; these do not.
+
+## Never
+
+- No em dashes. Use a comma, a colon, or a new sentence.
+- No sentence that sets up a claim only to knock down a weaker one first. State the claim.
+- No adjective standing in for evidence. If a sentence says a thing is important, it shows why.
+- No filler openers ("In today's world", "It goes without saying").
+- No exclamation marks outside quoted dialogue.
+
+## Always
+
+- The first line of a piece states what it is about.
+- A number carries its source, or it does not go in.
+- A quotation is word for word, or it is not in quotation marks.
+- One idea per paragraph. A paragraph that needs a second idea is two paragraphs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/hyperspec",
-  "version": "0.2.0",
+  "version": "0.3.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": {
@@ -15,6 +15,7 @@
     "src/",
     "examples/",
     "SPEC.md",
+    "WRITING.md",
     "runs.jsonl",
     "README.md",
     "CHANGELOG.md",
@@ -39,6 +40,6 @@
     "outcome-factory"
   ],
   "dependencies": {
-    "@supersuit/superskill": "^0.2.1"
+    "@supersuit/superskill": "^0.2.2"
   }
 }

package/src/placeholder.mjs

@@ -0,0 +1,20 @@
+// A value only a human or an agent would recognize as "not actually written yet" never counts as
+// present, wherever a presence check reads it:
+//
+// - null and ~ (the YAML reader hands these back as the literal strings "null" and "~" rather
+//   than resolving them to YAML's own null);
+// - the placeholder words a scaffold or a hurried author leaves behind: todo, tbd, fixme, xxx,
+//   placeholder, <placeholder>, n/a;
+// - a run of dashes, a run of question marks, or an ellipsis ("...", or the single character);
+// - any of those followed by trailing ".", ":" or "!" (TODO., tbd:, FIXME!).
+//
+// Matched only against the WHOLE trimmed value, case-insensitive: "TODO: write the opening" is
+// real text that happens to start with the word, and still counts as present. "none" is not on
+// the list, because it is a legitimate decided value ("rejects: none of the above").
+//
+// This is the one place this pattern is defined. src/rules.mjs (the core tests), src/writing.mjs
+// and src/writing-fields.mjs (the writing profile) all import str() from here rather than keeping
+// their own copy, so a word added here closes every presence check in the linter at once. The
+// rule exists because a scaffold that fills every field with "TODO" would otherwise lint clean.
+export const PLACEHOLDER = /^(?:null|~|(?:todo|tbd|fixme|xxx|placeholder|<placeholder>|n\/a|-+|\?+|\.\.\.|…)[.:!]*)$/is;
+export const str = (v) => { const t = typeof v === "string" ? v.trim() : ""; return PLACEHOLDER.test(t) ? "" : t; };

package/src/profiles.mjs

@@ -0,0 +1,50 @@
+// A profile is an opt-in: a spec sets profile: <name> and gains a typed map of extra content
+// (writing: for profile: writing) that this file's rules check, on top of everything the core
+// format already requires. Every profile finding still reports under one of the nine tests; a
+// profile adds no tenth test and no separate score.
+//
+// This is the one place that knows which profile names exist. Adding a profile means adding one
+// entry here; rules.mjs and score.mjs both go through this registry rather than naming "writing"
+// themselves, so a second profile needs no change to either.
+import { lintWriting, blockStatus } from "./writing.mjs";
+
+const str = (v) => (typeof v === "string" ? v.trim() : "");
+const f = (test, id, severity, message, fix) => ({ test, id, severity, message, fix });
+
+export const PROFILES = Object.freeze({
+  writing: Object.freeze({
+    lint: lintWriting,
+    // Block completeness for the CLI's "<name>: k/n blocks complete" line and its --json twin.
+    // Reads the same findings lint just produced, so the count and the findings can never
+    // disagree with each other.
+    status: (data, findings) => blockStatus(data, findings),
+  }),
+});
+
+// Own-property lookup only: a profile named after something every object inherits
+// (constructor, toString, __proto__) is an unknown profile, never a function to call.
+export const knownProfile = (name) => (Object.hasOwn(PROFILES, name) ? PROFILES[name] : undefined);
+
+// Runs the declared profile's rules against a loaded spec. A spec with no profile: at all runs no
+// profile rules, so an unprofiled spec lints exactly as it always has. A profile: this linter does
+// not know is a warning under test 7 (a stranger resuming the spec still needs to know its rules
+// were not checked), not a failure: an unknown profile is not necessarily a wrong one, only one
+// this version cannot yet check.
+export function lintProfile(spec) {
+  const name = str(spec?.data?.profile);
+  if (!name) return [];
+  const profile = knownProfile(name);
+  if (!profile) {
+    return [f(7, "unknown-profile", "warn", `this linter does not know profile "${name}"; its rules were not checked`, "Set profile: to one this linter knows (writing), or remove it.")];
+  }
+  return profile.lint(spec);
+}
+
+// The { name, complete, total } score.mjs merges into a passing profile's score, or undefined
+// when no profile ran or the declared one is unknown (nothing to count).
+export function profileStatus(data, findings) {
+  const name = str(data?.profile);
+  const profile = knownProfile(name);
+  if (!profile) return undefined;
+  return { name, ...profile.status(data, findings) };
+}

package/src/rules.mjs

@@ -1,5 +1,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
+import { lintProfile } from "./profiles.mjs";
+import { str } from "./placeholder.mjs";
 
 export const TESTS = Object.freeze([
   { n: 1, name: "every decision is accounted for" },
@@ -25,15 +27,13 @@ const FENCE = /^ {0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^ {0,3}\1[`~]*[ \t]*$|(?![
 const INLINE_CODE = /(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g;
 const prose = (body) => String(body || "").replace(FENCE, "").replace(INLINE_CODE, "");
 const list = (v) => (Array.isArray(v) ? v : []);
-// A value that is only null or ~ is a placeholder: the reader (@supersuit/superskill/yaml) keeps
-// these as the literal strings "null" and "~" rather than resolving them to YAML's own null, so
-// they must never count as present. A value that is only a YAML comment (source: # TODO) is
-// handled upstream since superskill 0.2.1: the reader returns "" for it, same as any other blank
-// scalar, so it already fails str()'s own emptiness check and needs no rule here. A QUOTED value
-// that happens to start with "#" (source: "# literal") is real text and must count as present.
-// Every presence check goes through str().
-const PLACEHOLDER = /^(null|~)$/is;
-const str = (v) => { const t = typeof v === "string" ? v.trim() : ""; return PLACEHOLDER.test(t) ? "" : t; };
+// str() (a value that is null/~/todo/tbd/fixme/xxx/placeholder never counts as present) is
+// shared, from src/placeholder.mjs: writing.mjs and writing-fields.mjs import the same function,
+// so a placeholder word closes every presence check in the linter at once. A value that is only a
+// YAML comment (source: # TODO) is handled upstream since superskill 0.2.1: the reader returns ""
+// for it, same as any other blank scalar, so it already fails str()'s own emptiness check and
+// needs no rule here. A QUOTED value that happens to start with "#" (source: "# literal") is real
+// text and must count as present.
 const f = (test, id, severity, message, fix) => ({ test, id, severity, message, fix });
 // The versions of the format this linter knows. A spec naming any other may follow rules it
 // cannot check, so it is warned about rather than failed.
@@ -52,6 +52,11 @@ export function lintSpec(spec) {
   const version = str(d.hyperspec);
   if (!KNOWN_VERSIONS.includes(version)) out.push(f(7, "hyperspec-version", "warn", `hyperspec version "${version}" is not one this linter knows (${KNOWN_VERSIONS.join(", ")})`, "Set hyperspec: to a version this linter knows, or upgrade @supersuit/hyperspec."));
 
+  // A spec with no profile: runs no profile rules at all, so it lints exactly as it always has.
+  // One declared runs that profile's own rules (writing.mjs for profile: writing), every finding
+  // still reported under one of the nine tests below; an unknown profile name is a warning here.
+  out.push(...lintProfile(spec));
+
   // 1 and 4, decisions
   const decisions = list(d.decisions);
   if (!decisions.length) out.push(f(1, "decisions", "fail", "no decisions are listed", "List every decision this kind of work has under decisions:, each decided, delegated or open."));
@@ -119,10 +124,17 @@ export function lintSpec(spec) {
   });
 
   // 7
-  const next = str(d.resume?.next_action);
-  if (!next) out.push(f(7, "next-action", "fail", "no resume.next_action", "Write the single concrete step that starts the next session."));
-  else if (NO_ACTION.test(next)) out.push(f(7, "next-action-vague", "fail", `next action "${next}" names no action`, "Name the concrete step."));
-  else if (CONVERSATION.test(next)) out.push(f(7, "next-action-vague", "fail", `next action "${next}" points into a conversation the next reader cannot see`, "State the step itself."));
+  // NO_ACTION is checked against the RAW trimmed value, ahead of str()'s placeholder-blanking:
+  // two of its own words (tbd, todo) are now also placeholder words str() treats as blank, and
+  // "next action names no action" is the more specific, more correct message for those than "no
+  // resume.next_action" would be (something WAS written; it just names no action).
+  const rawNext = typeof d.resume?.next_action === "string" ? d.resume.next_action.trim() : "";
+  if (rawNext && NO_ACTION.test(rawNext)) out.push(f(7, "next-action-vague", "fail", `next action "${rawNext}" names no action`, "Name the concrete step."));
+  else {
+    const next = str(d.resume?.next_action);
+    if (!next) out.push(f(7, "next-action", "fail", "no resume.next_action", "Write the single concrete step that starts the next session."));
+    else if (CONVERSATION.test(next)) out.push(f(7, "next-action-vague", "fail", `next action "${next}" points into a conversation the next reader cannot see`, "State the step itself."));
+  }
   if (CONVERSATION.test(prose(spec.body))) out.push(f(7, "conversation-pointer", "warn", "the body points into a conversation the next reader cannot see", "State the thing itself."));
 
   // 8

package/src/score.mjs

@@ -1,4 +1,5 @@
 import { TESTS } from "./rules.mjs";
+import { profileStatus } from "./profiles.mjs";
 
 export function score(findings, data = {}) {
   const failed = new Set(findings.filter((x) => x.severity === "fail").map((x) => x.test));
@@ -6,7 +7,12 @@ export function score(findings, data = {}) {
   const open = (Array.isArray(data.decisions) ? data.decisions : [])
     .filter((x) => String(x?.state || "").trim() === "open").map((x) => String(x.id || "").trim());
   const status = failed.size ? "fail" : open.length ? "blocked" : "pass";
-  return { tests, passed: tests.filter((t) => t.pass).length, open, status };
+  const out = { tests, passed: tests.filter((t) => t.pass).length, open, status };
+  // Only when a known profile ran: profileStatus returns undefined for no profile: at all, and
+  // for one this linter does not know (nothing to count when its rules were never checked).
+  const profile = profileStatus(data, findings);
+  if (profile) out.profile = profile;
+  return out;
 }
 
 export const exitCode = (status) => ({ pass: 0, fail: 1, blocked: 3 })[status] ?? 2;

package/src/template.mjs

@@ -4,7 +4,10 @@
 // which is also a valid YAML double-quoted scalar.
 const PLAIN = /^[A-Za-z0-9][A-Za-z0-9 _.,'()/-]*$/;
 const RESOLVES = /^(null|~|true|false|yes|no|on|off|y|n|[-+]?(\d[\d_]*)?\.?\d+([eE][-+]?\d+)?|0x[0-9a-f]+|0o[0-7]+|\.inf|\.nan)$/i;
-const scalar = (v) => (PLAIN.test(v) && !/\s$/.test(v) && !RESOLVES.test(v) ? v : JSON.stringify(v));
+// Exported so any other init-time template (writing-template.mjs's writingTemplate, and whatever
+// profile templates come after it) quotes titles, kinds and other free-text scalars the same way,
+// rather than re-deriving this regex pair.
+export const scalar = (v) => (PLAIN.test(v) && !/\s$/.test(v) && !RESOLVES.test(v) ? v : JSON.stringify(v));
 
 export function template({ title = "Untitled", kind = "document" } = {}) {
   const heading = String(title).replace(/\s+/g, " ").trim();