@supersuit/hyperspec 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # Changelog
 
+## 0.5.0 (2026-09-29)
+
+Scoped writer DNA. A writer does not have one voice: the same person writes differently for a
+theology journal and a landing page. So a writer's voice is now kept per scope, a form, an
+audience and a purpose, as a folder of goldens: real passages a person approved, each with a note
+on the move it teaches and where it came from. A golden feeds only work that shares its scope, so
+a passage that is right for one kind of writing never teaches its moves to another. hyperspec
+measures each scope's style from its goldens (sentence and paragraph length, punctuation,
+pronouns, signature words), counts and never judges, and still calls no model.
+
+**No behavior change for existing specs.** Scoped DNA is opt-in through a new optional field,
+`writing.dna.scope_dir`. A spec without it passes and fails exactly as it did in 0.4.0, and no
+finding id changed: every id below is new.
+
+- `hyperspec dna init <scope-dir> --writer W --form F --audience A --purpose P` writes a scope
+  folder: `scope.md` (writer, form, audience, purpose, optional notes) and a `goldens/` folder
+  holding a README on the golden file shape. It refuses to overwrite an existing `scope.md`, never
+  replaces a `goldens/README.md` that is already there, and
+  exits 2 with a plain message on a missing flag, a flag whose value is a placeholder, or a
+  parent folder that does not exist. Paths print as you gave them.
+- A golden is one `.md` file directly in `goldens/`, other than `README.md`: frontmatter `why`
+  (the move it teaches), `approved_by` (a person; an approver starting `agent:` is refused,
+  because golden means a human approved it) and `source` are required, `approved_on` is optional,
+  and the body is the passage, verbatim. A `goldens/` folder that resolves outside its scope, such
+  as a symlink to another scope's goldens, is refused under test 5, naming where it leads.
+- `hyperspec dna measure <scope-dir> [--json]` checks every golden and writes
+  `<scope-dir>/features.json`: the scope, each golden's path and SHA-256, and the features. If
+  the scope or any golden fails a check it writes nothing and exits 1, so a hollow or borrowed
+  golden is never measured in. The same goldens always produce the same bytes.
+- The features: word count; sentence length in words (mean, median, 90th percentile); paragraph
+  length in sentences and in words; per-1000-word rates of commas, semicolons, colons, em dashes,
+  en dashes, exclamation marks, question marks, parentheses and quotation marks; contraction,
+  first-person singular, first-person plural and second-person rates; mean word length; and up to
+  15 signature words. Sentences and paragraphs are split the same way `segments init` splits
+  them.
+- With `writing.dna.scope_dir`, `lint` checks that `scope.md` matches the spec's writer, form,
+  audience and purpose (test 1); that every golden the spec lists is one of the scope's goldens,
+  after following any symlink, and never a passage in a subfolder, in `README.md` or in another
+  kind of file (test 5); that every golden in the folder has its `why` (test 6), a person's
+  approval and a source (test 4) and a passage (test 1); and that `features.json` is exactly what
+  `dna measure` would write now (test 6). The stale finding names what differs: goldens added,
+  removed or changed, a changed `scope.md` field, an unknown format version, or a number edited by
+  hand. A `scope_dir` that is present but a placeholder fails test 1.
+- New finding ids, all starting `writing-dna-`: `scope-dir`, `scope-missing`,
+  `scope-file-<field>` (a scope's `scope.md` lacks writer, form, audience or purpose),
+  `scope-mismatch-<field>`, `goldens-missing`, `goldens-empty`, `goldens-outside`,
+  `golden-unreadable`, `golden-frontmatter`, `golden-empty`, `golden-approved-by`,
+  `golden-approved-by-agent`, `golden-source`, `golden-leak`, `golden-why`, `features-missing` and
+  `features-stale`. Every existing id is unchanged; in particular a spec whose own
+  `writing.dna.scope` lacks a field still reports `writing-dna-scope-form` (and `-audience`,
+  `-purpose`) as in 0.4.0. Every message names the scope folder as the spec wrote it and the
+  golden by its path inside the folder, never a folder on your machine. WRITING.md lists every one
+  with its test.
+- `hyperspec init --profile writing` shows `scope_dir: TODO` in the `dna` block, which fails until
+  it names a scope folder or is deleted.
+- Two new exports from `@supersuit/hyperspec/writing`: `readScope`, which reads a scope folder
+  and returns `{ scope, goldens, findings }` without throwing, and `measureFeatures`, which takes
+  an array of passages and returns the features `dna measure` writes.
+- The essay example takes its voice from a scope folder,
+  `examples/writing/dna/essay-new-managers-teach/`, with three goldens and a measured
+  `features.json`. Its two goldens moved there from `examples/writing/essay/goldens/`, and a third
+  was added. The story example keeps its goldens in the spec with no scope folder, and still
+  passes.
+- WRITING.md gains a Scoped DNA section: why a writer's DNA is scoped, the folder shape, the
+  golden file, both commands with their output, what each feature measures and what it is for,
+  staleness, naming a scope in a spec, every finding with its test, and the exports. README and
+  SPEC.md point at it.
+
+## 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

package/README.md

@@ -25,13 +25,16 @@ 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 dna init <scope-dir> --writer W --form F --audience A --purpose P` | Start a writer-DNA scope folder. Refuses to overwrite an existing `scope.md`. |
+| `hyperspec dna measure <scope-dir>` | Check every golden in a scope and write its measured features. |
 | `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`, `segments init` and `dna init` takes `--json`. `hyperspec --help` prints every flag.
 
 ## Exit codes
 
@@ -131,6 +134,48 @@ each rule reports under are in [WRITING.md](WRITING.md). Two complete specs that
 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"`.
+
+### Scoped DNA
+
+A writer sounds different in a theology essay and on a landing page, so a writer's voice is kept
+per scope (a form, an audience and a purpose), and each scope is a folder of goldens. A golden is a real
+passage a person approved, with a note on the move it teaches and where it came from, and it
+feeds only work that shares its scope.
+
+```bash
+mkdir -p dna
+npx @supersuit/hyperspec dna init dna/essay-new-managers-teach --writer example-author --form essay --audience "new managers" --purpose teach
+npx @supersuit/hyperspec dna measure dna/essay-new-managers-teach
+```
+
+`dna init` writes `scope.md` and a `goldens/` folder holding only a README. Add one file per
+golden, then `dna measure` checks each golden and writes `features.json`: sentence and paragraph length, punctuation,
+pronouns and signature words, measured and never judged. Name the folder in a spec as
+`writing.dna.scope_dir` and `lint` checks that the scope matches the spec, that no golden comes
+from another scope, and that the measurements are current. Without `scope_dir`, a spec lints as
+it did in 0.4. The folder shape, every feature, and every finding are in
+[WRITING.md](WRITING.md#scoped-dna); `readScope` and `measureFeatures` are exported from
+`@supersuit/hyperspec/writing`.
+
 ## The format
 
 A hyperspec is a markdown file with a YAML frontmatter block: `decisions`, `requirements`,

package/SPEC.md

@@ -97,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.3, the writing profile included, and cut 0.4 from them
+  next_action: collect adopter issues on 0.5, scoped DNA included, and cut 0.6 from them
 feedback:
   issues: https://github.com/SupersuitUp/hyperspec/issues
   fork: MIT; fork it for your own purposes and say so in your SPEC
@@ -109,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.3.0** (2026-09-29)
+**Version 0.5.0** (2026-09-29)
 
 ## What makes a spec a hyperspec
 
@@ -220,6 +220,8 @@ Each row lists every condition under which `hyperspec lint` fails that test. A w
 | 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). A writing spec that names a writer-DNA scope folder with `writing.dna.scope_dir` is also checked against it: the scope matches the spec (test 1), every golden has a person's approval and a source (test 4), no golden comes from outside the scope (test 5), and every golden has its why and the scope's measured features are current (test 6). `scope_dir` is optional, and without it nothing changes.
+
 ## Exit codes
 
 `hyperspec lint` reports the worst result across every file it is given:
@@ -243,7 +245,7 @@ Silence is not a verdict. A run that learned nothing has to say so and why, and
 
 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, and `hyperspec init --profile writing` are in [WRITING.md](WRITING.md).
+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`, marking materials with `hyperspec segments init`, and scoped writer DNA with `hyperspec dna init` and `hyperspec dna measure` are in [WRITING.md](WRITING.md).
 
 ## Recipes