@supersuit/hyperspec 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # Changelog
 
+## 0.4.0 (2026-09-29)
+
+Marking materials. Before a writing spec can pass, every material it draws on (a brain dump, a
+transcript, a set of interview notes) is split into segments, and each segment is labeled with
+what a draft may use it as: a claim with its source, the author's own claim, a story with its
+teller, a quote with its speaker, a stance, an open question, an aside, or something private.
+The spine then cites segments rather than whole files, so every claim points at the exact words
+behind it. hyperspec splits and checks; an agent or a person labels. It still calls no model.
+
+**Behavior change for 0.3 writing specs:** a writing spec's materials must now be marked. A
+material item with no `segments:` field fails test 1, so a writing spec that passed 0.3.0 fails
+until each of its materials has a segments file, written with `hyperspec segments init` and
+labeled. Specs with no profile are unaffected.
+
+- `hyperspec segments init <material> --id <mid> [--out <file>] [--by paragraph|sentence]`
+  writes `<material>.segments.jsonl`: a header naming the material, its path and the SHA-256 of
+  its bytes, then one line per segment with character offsets, the verbatim text, and the label
+  `unlabeled`. Paragraph mode is the default. It refuses to overwrite a file, and exits 2 with a
+  plain message on a missing material, a material with nothing in it, an `--out` folder that
+  does not exist, or an unknown `--by`.
+- In sentence mode, a new line that opens on a list marker (`-`, `*`, `+`, or a number followed
+  by `.` or `)`, then a space) starts a new segment, and a numbered item's own `1.` is not read
+  as a sentence ending. A bullet that is entirely a quotation ending in `."` used to run into the
+  next bullet; it now stands on its own. Paragraph mode is unchanged.
+- Seven labels, a closed set: `claim` (needs `source`, or `own: true`), `story` (needs
+  `teller`), `quote` (needs `speaker`), `stance`, `question`, `aside` and `private`. `unlabeled`
+  is never accepted. A placeholder word (`TODO`, `n/a`, `tbd`, `...`, `???` and the rest) counts
+  as missing in these fields, in the header, and in segment ids, as it does everywhere else in
+  the linter.
+- What `lint` checks on each segments file, under test 1: the file exists and parses, its header
+  names the right material, every label is from the set, ids are unique, and segments never
+  overlap and cover every character that is not whitespace (the finding quotes the first
+  uncovered text and gives its offset), and the material has some text to mark. Under test 4: every segment's text
+  matches the material word for word, each label carries the field it needs, and the material
+  has not changed since it was marked (its SHA-256 still matches). A changed material fails as
+  stale until it is marked again.
+- A spine claim may cite `material#segment`. The segment must exist (test 4), and citing a
+  `private` or `question` segment fails test 5. A bare material id still cites the whole
+  material; `material#` with nothing after the `#` fails as an unknown segment.
+- Every marking finding id starts `writing-materials-` or `writing-spine-`, and every message
+  names the material, and the segment where there is one. Paths in messages read as the spec
+  wrote them, never resolved to a folder on your machine, so `--json` output is the same
+  everywhere. WRITING.md lists every finding with its test.
+- A new export, `@supersuit/hyperspec/writing`, gives your own tools `MATERIAL_LABELS` and
+  `readSegments`, the same parse-and-check lint runs. `readSegments` returns
+  `{ header, segments, findings }` and never throws; `displayPath` and `materialDisplayPath` set
+  how the files are named in its messages.
+- `hyperspec init --profile writing` names a segments file for its placeholder material, and the
+  materials check reads "every segment of every material carries a label from the closed set,
+  matches its source verbatim, and the markings are current".
+- Both writing examples ship with every material marked. Between them they use all seven labels,
+  and every spine claim cites segments.
+- WRITING.md gains a Marking materials section: the file format with a worked sample, the labels
+  and what each needs, coverage, staleness (including a line-ending conversion, which changes the
+  hash), citing segments, every finding with its test, and the import. README and SPEC.md point
+  at it.
+- The repository's `.gitattributes` keeps example materials and test fixtures LF on every
+  checkout, so the hashes their segments files pin still match on a Windows clone.
+
+## 0.3.0 (2026-09-29)
+
+The writing profile. A piece of writing can now carry a hyperspec that names everything an
+agent would otherwise fill with the average: what the piece is made from and how far each
+source can be trusted, whose voice it is for this form, audience and purpose, who it speaks as,
+who reads it, the one change it is for, what kind of thing it is, the claims it argues in order,
+where every fact comes from, and in fiction how each character speaks and what they know by
+each scene. `hyperspec lint` checks all of it under the same nine tests, and
+`hyperspec init --profile writing` lays every block out for you to fill in.
+
+**Behavior change for existing specs:** a placeholder now counts as missing, everywhere, in
+specs with no profile too. A placeholder is a whole value, trimmed and in any case, of `todo`,
+`tbd`, `fixme`, `xxx`, `placeholder`, `<placeholder>`, `n/a`, a run of dashes, a run of question
+marks, or an ellipsis, optionally followed by a trailing `.`, `:` or `!`. A spec that passed
+0.2.0 with `source: TODO` or `source: n/a` on a decision now fails that test. Real text that
+starts with one of those, such as `TODO: write the opening`, still counts as present, and so
+does `none`.
+
+- `profile: writing` opts a spec in; its blocks live under a top-level `writing:` map:
+  `materials`, `dna`, `persona`, `audience`, `goal`, `form`, `spine`, `sources`, and
+  `characters`, which is required when `fiction: true`. Every block carries a `check`, a
+  `source` and an `author`. The core format still applies in full.
+- No tenth test. Every writing finding reports under one of the nine, with an id starting
+  `writing-`, and the score stays out of nine. `lint` prints one more line,
+  `writing: <k>/9 blocks complete`, and `--json` carries it as `profile` on each file.
+- A missing block fails test 1 unless a decision with the id `writing-<block>` defers it:
+  `open`, which blocks the spec like any open decision, or `delegated` with a `rule`. A
+  deferred block does not count as complete.
+- Progress is never stored: a `writing.progress` key fails test 7, because saved progress goes
+  stale the first time a session dies mid-arc. Progress is read off the folder instead.
+- Field rules for every block, each under the test it belongs to: closed sets for `fiction`
+  (absent means false), `trust`, `reader`, `change.kind`, the shape of `persona.identity` and
+  `unsourced_claim`; unique ids for materials, spine claims and characters; a length envelope
+  of whole numbers of at least 1 (test 1); five to ten distinct `goal.conditions` naming real
+  requirements, each listed once (test 2); spine claims that name real materials (test 4);
+  `persona.facts_from: sources` and a non-empty `will_not_say` (test 5); a `why` on every
+  golden, material and golden paths that exist, and golden and rejected lines for every
+  character with no line in both (test 6). A repeated id counts once toward a minimum. A
+  `stance` outside peer, mentor, witness and guide is a warning.
+- A character needs speech rules (what they say and never say), wants, fears, what they hide,
+  an arc state, a knowledge timeline, and golden and rejected lines. `relationships` and a
+  pointer to a character `entity` file are optional.
+- `hyperspec init <file> --profile writing [--title T] [--form F] [--fiction]` writes a
+  skeleton with every required block in schema order, every field a placeholder, and open
+  decisions for the four blocks that need your judgment first (dna, persona, audience, goal).
+  It fails lint until the placeholders are replaced. `init` exits 2 with a plain message on a
+  `--profile` with no value or one it does not know, `--fiction` or `--form` without
+  `--profile writing`, `--kind` with it, and a folder that does not exist.
+- `lint` warns under test 7 on a `profile` it does not know, and checks none of its rules. A
+  name every object inherits, such as `constructor`, is an unknown profile like any other.
+- WRITING.md documents the profile: the ten components, the schema with every field, the test
+  mapping, the closed sets, the seven materials labels and what each may be used as, and
+  deferral. It ships in the package.
+- `examples/writing/` ships two complete specs, an essay and a two-character short story, with
+  every file they name. Both pass with no findings, and a test keeps them that way.
+- SPEC.md gains a Profiles section and states the placeholder words in its test-to-field map.
+- The illustrative specs and recipe in SPEC.md and `examples/minimal.hyperspec.md` name a
+  placeholder author, `example-author`, and a placeholder factory, `my-factory`.
+- Requires `@supersuit/superskill` 0.2.2, whose YAML reader reads an inline map (`scope: { form: essay, purpose: persuade }`), a bare inline map as a list item, and an inline list followed by a comment. On 0.2.1 those came back as text, so a correct spec written in that compact style failed. A test lints the essay example rewritten in that style.
+
 ## 0.2.0 (2026-09-28)
 
 Recipes. Every output a factory makes can now carry a recipe beside it: what made it, from

package/README.md

@@ -24,13 +24,15 @@ improvement ledger. Every test is defined in [SPEC.md](SPEC.md).
 |---|---|
 | `hyperspec lint <file...> [--json]` | Score each hyperspec against the nine tests. |
 | `hyperspec init <file> [--title T] [--kind K]` | Write a new hyperspec skeleton. Refuses to overwrite an existing file. |
+| `hyperspec init <file> --profile writing [--title T] [--form F] [--fiction]` | Write a writing-spec skeleton, every block shown with placeholders. |
+| `hyperspec segments init <material> --id <mid> [--out F] [--by paragraph\|sentence]` | Split a material into segments to label. Refuses to overwrite an existing file. |
 | `hyperspec recipe check <output-or-recipe>` | Check that a recipe records everything the standard asks for. |
 | `hyperspec recipe approve <recipe> --by <slug>` | Record who approved the output. |
 | `hyperspec reproduce <recipe> [--restore]` | Re-check every hash the recipe recorded. Never runs a model. |
 | `hyperspec regenerate <recipe> --out <path> --clicker <slug> <one change> [--run cmd]` | Make a child recipe from a parent and one named change, rerunning only the stages it reaches. |
 | `hyperspec compare <child-recipe> --doctor cmd` | Grade a child and its parent through one doctor against one spec. |
 
-Every command except `init` takes `--json`. `hyperspec --help` prints every flag.
+Every command except `init` and `segments init` takes `--json`. `hyperspec --help` prints every flag.
 
 ## Exit codes
 
@@ -103,11 +105,59 @@ recipe.finish();
 The schema, the stage key, the runner and doctor contracts, and every exit code are in
 [SPEC.md](SPEC.md#recipes).
 
+## Writing specs
+
+A piece of writing gets its own profile. Add `profile: writing` to a hyperspec and it gains nine
+blocks that name what an agent would otherwise fill with the average: the materials it draws on
+and how far each can be trusted, the writer's voice scoped to this form, audience and purpose,
+who the piece speaks as, who reads it and what they already know, the one change the piece is
+for, its form, the claims it argues in order, where every fact comes from, and in fiction every
+character who speaks. Findings still report under the nine tests, and `lint` adds one line:
+
+```
+essay.hyperspec.md: pass (9/9)
+  writing: 9/9 blocks complete
+```
+
+Start one with every block laid out and waiting:
+
+```bash
+npx @supersuit/hyperspec init essay.hyperspec.md --profile writing --title "Your title"
+npx @supersuit/hyperspec init story.hyperspec.md --profile writing --form "short story" --fiction
+```
+
+The skeleton fails until every placeholder is real and its four open questions (whose voice,
+who speaks, who reads, what changes) are answered. The blocks, every field, and which test
+each rule reports under are in [WRITING.md](WRITING.md). Two complete specs that pass with
+nothing to warn ship in `examples/writing/`: an essay for new managers, and a short story with
+two characters whose voices a judge can tell apart.
+
+### Marking materials
+
+Every material a writing spec draws on is marked before the spec can pass: split into segments,
+and each segment labeled with what it may be used as (claim, story, quote, stance, question,
+aside, private). hyperspec does the splitting and the checking; an agent or a person does the
+labeling.
+
+```bash
+npx @supersuit/hyperspec segments init materials/voice-memo.md --id voice-memo
+npx @supersuit/hyperspec lint essay.hyperspec.md
+```
+
+The first writes `materials/voice-memo.md.segments.jsonl`, every segment `unlabeled`. Name that
+file as `segments:` on the material item, label every segment, and `lint` checks that each label
+is from the set and carries what it needs, that each segment matches the material word for word,
+that the material has not changed since, and that no spine claim cites a private or question
+segment. The file format, the labels, and every finding are in
+[WRITING.md](WRITING.md#marking-materials). A tool of your own can run the same check with
+`import { readSegments } from "@supersuit/hyperspec/writing"`.
+
 ## The format
 
 A hyperspec is a markdown file with a YAML frontmatter block: `decisions`, `requirements`,
-`rejects`, `examples`, `resume`, `feedback`, and `improvement`. The full field-by-field
-standard, including what makes each of the nine tests fail, is in [SPEC.md](SPEC.md).
+`rejects`, `examples`, `resume`, `feedback`, and `improvement`, plus an optional `profile`.
+The full field-by-field standard, including what makes each of the nine tests fail, is in
+[SPEC.md](SPEC.md).
 
 ## Install
 

package/SPEC.md

@@ -39,6 +39,12 @@ decisions:
     source: SPEC.md, section "Recipes"
     author: agent:claude
     chosen_by: agent
+  - id: profiles
+    state: decided
+    value: a profile adds rules for one kind of work under the nine tests; it never adds a tenth test, every finding it raises names one of the nine, and the score stays out of nine
+    source: WRITING.md, section "The writing profile"
+    author: agent:claude
+    chosen_by: agent
 requirements:
   - id: r1
     text: lint exits 0 only when all nine tests pass and nothing is open
@@ -91,7 +97,7 @@ examples:
   - path: examples/minimal.hyperspec.md
     why: the smallest spec that passes all nine tests
 resume:
-  next_action: collect adopter issues on 0.2, recipes included, and cut 0.3 from them
+  next_action: collect adopter issues on 0.4, materials marking included, and cut 0.5 from them
 feedback:
   issues: https://github.com/SupersuitUp/hyperspec/issues
   fork: MIT; fork it for your own purposes and say so in your SPEC
@@ -103,7 +109,7 @@ improvement:
 
 A person writing for another person leaves most of the specification unsaid, because the other person fills the gaps from shared context. An agent has none of that context, so it fills every gap with the average, and the average is what reads as middling. Hyperspecification is writing down the gaps. It is a level of detail that would feel like overkill between two people and is exactly enough for an agent: every decision the agent would otherwise guess is either decided, delegated with the rule for deciding it, or marked open, so the work stops instead of guessing.
 
-**Version 0.2.0** (2026-09-28)
+**Version 0.4.0** (2026-09-29)
 
 ## What makes a spec a hyperspec
 
@@ -161,7 +167,7 @@ decisions:
     state: decided            # decided | delegated | open
     value: the operator, reading on a phone
     source: interview A2      # where it came from
-    author: gary-sheng        # a person slug, or agent:<model>
+    author: example-author    # a person slug, or agent:<model>
     chosen_by: human          # human | agent
   - id: length
     state: delegated
@@ -182,7 +188,7 @@ requirements:
     check:
       rubric: ask the simulated reader to define the term; pass only on a correct definition
     source: design doc, audience block
-    author: gary-sheng
+    author: example-author
 rejects:
   - hype words about AI
 examples:
@@ -200,7 +206,7 @@ improvement:
 
 ## The test-to-field map
 
-Each row lists every condition under which `hyperspec lint` fails that test. A warning never fails a test. A value that is only a YAML comment (`source: # TODO`), or `null`, or `~`, counts as missing. A quoted value that happens to start with `#` (`source: "# literal"`) is real text and counts as present.
+Each row lists every condition under which `hyperspec lint` fails that test. A warning never fails a test. A value that is only a YAML comment (`source: # TODO`), `null`, `~`, or a placeholder counts as missing. A placeholder is a whole value, trimmed and in any case, of `todo`, `tbd`, `fixme`, `xxx`, `placeholder`, `<placeholder>`, `n/a`, a run of dashes, a run of question marks, or an ellipsis, optionally followed by a trailing `.`, `:` or `!`. Real text that starts with one of those (`TODO: write the opening`) counts as present, and so do `none` and a quoted value that happens to start with `#` (`source: "# literal"`).
 
 | Test | Fails when |
 |---|---|
@@ -210,10 +216,12 @@ Each row lists every condition under which `hyperspec lint` fails that test. A w
 | 4 every field says where it came from and who wrote it | a decision or requirement without `source` or `author`; a decision whose `chosen_by` is not human or agent |
 | 5 negative space is specified | `rejects` missing or empty; a `rejects` item that is not a plain string |
 | 6 examples outrank adjectives | `examples` missing or empty; an example without `path` or `why`; a `path` that is not an http(s) URL and does not exist, is a folder, or is the spec itself, read relative to the spec or as an absolute path |
-| 7 a stranger can resume it | `resume.next_action` missing; a `next_action` that is only a no-action word (`continue`, `follow up`, `tbd`, `todo`, `keep going`, `pick it back up`, `n/a`, `none`); a `next_action` that says `as discussed` or `as mentioned earlier` or `above`. Those pointers in the body are a warning, and so is a `hyperspec` version this linter does not know |
+| 7 a stranger can resume it | `resume.next_action` missing; a `next_action` that is only a no-action word (`continue`, `follow up`, `tbd`, `todo`, `keep going`, `pick it back up`, `n/a`, `none`); a `next_action` that says `as discussed` or `as mentioned earlier` or `above`. Those pointers in the body are a warning, and so are a `hyperspec` version and a `profile` this linter does not know |
 | 8 its adopters can push back on it | `feedback.issues` or `feedback.fork` missing |
 | 9 it improves itself | `improvement.ledger` missing; a ledger path that exists and is not a readable file; if the ledger file exists, a line that is not a JSON object, a `verdict` outside one-shot, improved or not-improved, `improved` without `change`, `not-improved` without `reason`. A declared ledger that does not exist yet is a warning |
 
+A profile adds its own conditions to these rows. The writing profile's are in [WRITING.md](WRITING.md#the-test-mapping), including the checks on each material's segments file: every material marked, every segment labeled from the closed set and matching its material word for word, the marking current (tests 1 and 4), and no spine claim citing a private or question segment (test 5).
+
 ## Exit codes
 
 `hyperspec lint` reports the worst result across every file it is given:
@@ -233,6 +241,12 @@ Every run of a skill that works from a hyperspec writes one line to the ledger n
 
 Silence is not a verdict. A run that learned nothing has to say so and why, and a ledger line with none of the three verdicts fails the ninth test.
 
+## Profiles
+
+A profile adds the rules for one kind of work on top of the nine tests. A spec opts in with a top-level `profile:` naming it. A profile never adds a tenth test: every finding it raises reports under one of the nine, with an id that starts with the profile's name, and the score stays out of nine. `lint` prints one more line for a profiled spec, how many of the profile's blocks are complete. A `profile` this linter does not know is a warning under test 7, and none of its rules are checked.
+
+One profile ships: `writing`, for essays, chapters, letters, stories and anything else an agent drafts for a person to read. Its blocks, its fields, which test each rule reports under, `hyperspec init --profile writing`, and marking materials with `hyperspec segments init` are in [WRITING.md](WRITING.md).
+
 ## Recipes
 
 A hyperspec says what the work must be. A recipe records what one output was made from, so the output can be checked, made again with one change, and graded against the version before it. hyperspec never calls a model. Every step that needs one is a command the caller supplies: a runner for stages and a doctor for grading.
@@ -246,8 +260,8 @@ A recipe sits beside its output as `<output>.recipe.json`: JSON with a two-space
   "recipe": "0.1",
   "created": "2026-09-28T18:00:00.000Z",
   "output": { "path": "essay.md", "sha256": "<hex>" },
-  "factory": { "name": "compose-a-piece", "version": "0.3.0" },
-  "spec": { "path": "essay.hyperspec.md", "sha256": "<hex>", "authors": { "audience": "gary-sheng", "length": "agent:claude" } },
+  "factory": { "name": "my-factory", "version": "0.3.0" },
+  "spec": { "path": "essay.hyperspec.md", "sha256": "<hex>", "authors": { "audience": "example-author", "length": "agent:claude" } },
   "inputs": [
     { "name": "call", "path": "materials/call.md", "sha256": "<hex>", "order": 1 }
   ],
@@ -261,8 +275,8 @@ A recipe sits beside its output as `<output>.recipe.json`: JSON with a two-space
       "verdict": { "station": "outline-has-claim-chain", "pass": true, "note": "" }
     }
   ],
-  "clicker": "gary-sheng",
-  "approver": "gary-sheng",
+  "clicker": "example-author",
+  "approver": "example-author",
   "parent": null,
   "change": null
 }