@supersuit/hyperspec 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 0.6.0 (2026-09-29)
+
+A spec can now check a draft. Until this release hyperspec could tell you whether a writing spec
+was ready; it could not tell you whether the piece written from it met the spec. `hyperspec
+check` runs seven deterministic stations against a draft: the length and required parts, the
+terms the reader needs defined, the claims ledger, quotations, private material, the writer's
+measured style, and links. None of them calls a model or touches the network, so the same draft
+and spec always give the same answer. Each run leaves one line in the spec's runs ledger saying
+whether the draft passed first time, improved, or did not, and why.
+
+**No behavior change for lint.** Every spec without `writing.audience.terms` passes and fails
+exactly as it did in 0.5.0, and no lint finding id changed. That field is the one schema
+addition, and it is optional.
+
+- `hyperspec check <spec> --draft <file> [--json] [--only a,b]` needs a writing spec
+  (`profile: writing`) and lints it first: a spec that fails lint, or is blocked on an open
+  decision, runs no station and exits with lint's code. Then it runs every station in a fixed
+  order, `form, terms, claims, quotes, private, dna, links`, and prints each one's `pass`, `fail`
+  with findings, or `skip` with the reason. Warnings print under their station and never fail it.
+  Exit 0 when every station that ran passed, 1 when one failed, 2 on usage (no spec, no
+  `--draft`, an unreadable draft, a spec without the writing profile, an `--only` that names no
+  known station); under `--json` a usage error is one document, `{ spec, draft, error }`.
+  `--only` runs a subset, still in the fixed order. A finding names the draft line it points at
+  where there is one, quotes at most 80 characters of the draft, and never prints an absolute
+  path. A byte order mark at the start of the draft is ignored. A station that throws becomes one
+  failing finding, `station-<name>-crashed`, and the rest still run.
+- `form`: word count against `writing.form.length` (only `unit: words` is measured; another unit
+  skips the station), and every `required_parts` entry present as an ATX heading of that text
+  (indented up to three spaces, closing `#`s allowed), or as a line starting `part:`, outside
+  code blocks.
+- `terms`: every term in the new optional `writing.audience.terms`, other than those in `knows`,
+  is defined at its first appearance: in that sentence or the next, the term followed within six
+  words by `is`, `means`, `refers to` or a colon, or by a parenthesis. A mechanical proxy for a
+  definition, and documented as one. No `terms` list: skip.
+- `claims`: every claim in the JSONL ledger at `writing.sources.ledger` (`text`, `source`,
+  optional `span`) still appears in the draft word for word, and has a real source; unsourced
+  claims warn instead under `unsourced_claim: warn`, and point at the draft line where the claim
+  appears. A missing ledger fails. The ledger is the list of claims: the station does not decide
+  what counts as one.
+- `quotes`: every double-quoted span of four words or more appears word for word in a `quote` or
+  `story` segment of a marked material, never a private one; when the sentence names a quote
+  segment's speaker, by the full name or by its first word (when that word has two or more
+  letters and is not a common function word such as "the"), the span must come from that
+  speaker. A spec with `fiction: true` skips the station, since a character's dialogue is
+  invented rather than quoted.
+- `private`: no run of eight words from a `private` segment appears in the draft. Segments of four
+  to seven words are checked whole; shorter ones are counted in one warning and never quoted.
+- `dna`: with a current `writing.dna.scope_dir`, the draft is measured the way goldens are and
+  each feature compared with the scope's, from v ÷ 1.5 to the larger of v × 1.5 and v + 5; drift,
+  and an em dash where the scope has none (pointing at the first one), are warnings. No scope
+  folder: skip.
+- `links`: inline, reference and bare links are well-formed http, https or mailto (a bare
+  `https://` with no host fails); relative links resolve to a file beside the draft; a `/` link
+  warns, since there is no site root to resolve it against; a full or collapsed reference needs
+  its definition. A bare `[label]` is a link only when its label is defined, so `[sic]`, `[x]` and
+  `[1]` are text. No network access.
+- The runs ledger: each check appends `{ at, kind: "check", draft, draft_sha256, spec_sha256,
+  stations, verdict }` to `improvement.ledger`, with `draft` relative to the spec's folder. A run
+  with `--only` adds `partial: true`, is `not-improved` with the reason `partial run: <stations>`,
+  and is ignored by later verdicts. A full run is compared with the last full line for the same
+  draft: `one-shot` when there is none and every station passes; `improved` when that line failed
+  and every station passes now, with `change` naming exactly the stations that failed then and
+  pass now; otherwise `not-improved`, with a `reason` that says which case it is, such as "no
+  change since the last passing check" or "spec changed; failing stations: terms". The lines keep
+  lint's test 9 passing.
+- New optional field `writing.audience.terms`: a list of real strings when present (test 1,
+  `writing-audience-terms`, naming a scalar that is not a list, an empty list, and each entry that
+  is not a string, is empty or is a placeholder). Absent, nothing changes.
+- The worked examples each ship a draft that passes every station, with its claims ledger:
+  `examples/writing/essay/draft.md` and `examples/writing/story/draft.md`. Both specs now list
+  `audience.terms`, and their `required_parts` are the drafts' headings. The essay's interview
+  quotes now name their speaker `dana, an engineering manager`, and the essay links the survey
+  summary it cites. A test runs `check` on both. WRITING.md gains "Checking a draft": each station, what it cannot check, a findings table
+  per station held by a test to the ids the stations raise, and the ledger line.
+
 ## 0.5.0 (2026-09-29)
 
 Scoped writer DNA. A writer does not have one voice: the same person writes differently for a

package/README.md

@@ -28,6 +28,7 @@ improvement ledger. Every test is defined in [SPEC.md](SPEC.md).
 | `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 check <spec> --draft <file> [--only a,b]` | Run a writing spec's deterministic stations against a draft. |
 | `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. |
@@ -42,6 +43,10 @@ Every command except `init`, `segments init` and `dna init` takes `--json`. `hyp
 test fails, 3 when every test passes but a decision is still open (blocked), and 2 on a usage
 error or a file that cannot be read, has broken frontmatter, or is not a hyperspec.
 
+`hyperspec check` exits 0 when every station it ran passed, 1 when one failed, and 2 on a usage
+error, a draft that cannot be read, or a spec without `profile: writing`. A spec that is not ready to check against exits with lint's
+own code, 1 or 3, and no station runs.
+
 The recipe commands use the same numbers: 0 ok, 1 a check failed or the child regressed, 2
 usage or unreadable input, 3 pending, when `regenerate` has stages waiting for a runner.
 `regenerate` also exits 1 when a stage it ran reported a failing verdict, or none. A stage it
@@ -132,7 +137,7 @@ The skeleton fails until every placeholder is real and its four open questions (
 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.
+two characters whose voices a judge can tell apart. Each comes with a draft written to it.
 
 ### Marking materials
 
@@ -176,6 +181,25 @@ 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`.
 
+### Checking a draft
+
+Once a draft exists, `check` holds it to its spec with seven stations, none of which calls a
+model or touches the network: `form` (length and required parts), `terms` (every word in the new
+optional `writing.audience.terms` is defined where it first appears), `claims` (the claims
+ledger still matches the draft, and every claim has a source), `quotes` (in nonfiction, every quotation of four
+words or more is word for word in a marked quote), `private` (no run of eight words from a
+private segment), `dna` (the draft's measured style beside its scope's, as warnings) and `links`
+(well-formed, and relative links resolve).
+
+```bash
+npx @supersuit/hyperspec check essay.hyperspec.md --draft essay/draft.md
+```
+
+It lints the spec first, prints each station's pass, fail or skip, and appends one line to the
+spec's runs ledger with a verdict. Both examples ship a draft that passes. What each station
+checks and cannot check, and every finding, are in
+[WRITING.md](WRITING.md#checking-a-draft).
+
 ## 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.5, scoped DNA included, and cut 0.6 from them
+  next_action: collect adopter issues on 0.6, the check command included, and cut 0.7 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.5.0** (2026-09-29)
+**Version 0.6.0** (2026-09-29)
 
 ## What makes a spec a hyperspec
 
@@ -220,7 +220,7 @@ 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.
+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. The writing profile also has an optional `writing.audience.terms`, the words a piece uses that its reader may not know: when present it must list real terms (test 1), and `hyperspec check` reads it to require each term's definition where the draft first uses it. Without it nothing changes.
 
 ## Exit codes
 
@@ -236,7 +236,7 @@ A profile adds its own conditions to these rows. The writing profile's are in [W
 Every run of a skill that works from a hyperspec writes one line to the ledger named in `improvement.ledger`, one JSON object per line, with a `verdict`:
 
 - **one-shot**: no intervention, nothing to learn.
-- **improved**: the skill, the spec template, or a component library changed, and the line carries `change`, naming what changed.
+- **improved**: the skill, the spec template, or a component library changed, and the line carries `change`, naming what changed. On a `kind: "check"` line, which `hyperspec check` writes, it means the draft now passes every station after the last full check of it failed, and `change` names those stations.
 - **not-improved**: nothing changed, and the line carries `reason`, a reason a later session can argue with, such as "the correction was about this piece only" or "the fix belongs to a shipped skill and was filed as an issue".
 
 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.

package/WRITING.md

@@ -209,6 +209,8 @@ writing:
     wants: a plan for the first meeting
     reads_on: a phone, in the ten minutes before the meeting
     reader: person                   # person | agent
+    terms:                           # optional: terms the piece uses that the reader may not know
+      - skip-level
     check:
       station: term check against knows
       rubric: simulated reader reports where it got lost
@@ -317,6 +319,17 @@ cannot pass a presence check. A placeholder is a whole value, trimmed and in any
 marks, or an ellipsis, optionally followed by a trailing `.`, `:` or `!`. Real text that starts
 with one of those, such as `TODO: write the opening`, counts as present, and so does `none`.
 
+`audience.terms` is checked by the `terms` station in `hyperspec check`, and that check is a
+**mechanical proxy, not an understanding of meaning**: it looks for a definition-SHAPED phrase
+near the term's first appearance (the word `is`, `means`, `refers to`, a colon within a few words,
+or an immediate parenthetical), not for whether that phrase defines the term. A sentence
+like "A hyperspec is mentioned here" reads as a definition of "hyperspec" by this rule, because
+`is` immediately follows the word, even though nothing about the term is explained. This is
+deliberate and known, not a bug to fix later in this station: reading for meaning is a judgment
+call, and hyperspec's deterministic stations do not make judgment calls. A later release adds a
+simulated-reader station that reads for meaning instead of shape; `terms` stays the fast,
+mechanical first pass.
+
 ## The test mapping
 
 Each row lists what the writing profile adds to that test. The core conditions in
@@ -324,7 +337,7 @@ Each row lists what the writing profile adds to that test. The core conditions i
 
 | Test | A writing spec fails it when |
 |---|---|
-| 1 every decision is accounted for | a required block is missing and not deferred; a required field is missing; a closed-set value is outside its set (`trust`, `reader`, `change.kind`, the shape of `identity`, `unsourced_claim`); `identity: character:<id>` names a character that is not in `writing.characters`; `fiction` is present and is anything other than `true` or `false`; two materials, two spine claims or two characters share an id; `form.length.min` or `max` is not a whole number of at least 1, or `min` is greater than `max`; `spine.claims` has fewer than three or more than seven distinct claims; a character has no knowledge entry, or an entry lacks `by` or `knows`; a material has no text, or no `segments` field, or its segments file is missing, malformed, labels a segment outside the seven (`unlabeled` included), repeats a segment id, or has segments that overlap or leave text uncovered; `dna.scope_dir` is present and is a placeholder; with `dna.scope_dir`, its `scope.md` is missing, unreadable or lacks a field, its writer, form, audience or purpose differs from the spec's, or its `goldens/` folder is missing or empty, or holds a golden that cannot be read, whose frontmatter never closes, or that has no passage. A `stance` outside the four is a warning, and so is `unsourced_claim: warn` |
+| 1 every decision is accounted for | a required block is missing and not deferred; a required field is missing; a closed-set value is outside its set (`trust`, `reader`, `change.kind`, the shape of `identity`, `unsourced_claim`); `identity: character:<id>` names a character that is not in `writing.characters`; `fiction` is present and is anything other than `true` or `false`; two materials, two spine claims or two characters share an id; `form.length.min` or `max` is not a whole number of at least 1, or `min` is greater than `max`; `spine.claims` has fewer than three or more than seven distinct claims; a character has no knowledge entry, or an entry lacks `by` or `knows`; a material has no text, or no `segments` field, or its segments file is missing, malformed, labels a segment outside the seven (`unlabeled` included), repeats a segment id, or has segments that overlap or leave text uncovered; `dna.scope_dir` is present and is a placeholder; with `dna.scope_dir`, its `scope.md` is missing, unreadable or lacks a field, its writer, form, audience or purpose differs from the spec's, or its `goldens/` folder is missing or empty, or holds a golden that cannot be read, whose frontmatter never closes, or that has no passage; `audience.terms`, when present, holds a non-string entry or has no real entries at all. A `stance` outside the four is a warning, and so is `unsourced_claim: warn` |
 | 2 every requirement can fail | `goal.conditions` lists fewer than five or more than ten distinct ids, lists an id twice, or names an id that is not a top-level requirement |
 | 3 every requirement names its check | a block or a character has no `check` with a `station` or a `rubric` |
 | 4 every field says where it came from and who wrote it | a block or a character has no `source` or no `author`; a spine claim names no materials, or names a material id that is not in `materials.items`, or a segment that is not in that material's segments file; a segment's text does not match its material word for word; a material changed after it was marked; a claim segment has no `source` and no `own`, a story no `teller`, a quote no `speaker`; with `dna.scope_dir`, a golden in the scope has no `approved_by`, an approver that starts `agent:`, or no `source` |
@@ -786,6 +799,216 @@ source, and a `features.json` that `dna measure` wrote. A test measures the fold
 release and requires the same bytes, so the example cannot drift from the tool. The short story
 beside it lists its goldens in the spec with no scope folder, the 0.4 shape, which still passes.
 
+## Checking a draft
+
+Once a spec lints clean and a draft exists, `check` runs the spec's deterministic stations
+against the draft:
+
+```bash
+npx @supersuit/hyperspec check essay.hyperspec.md --draft essay/draft.md
+```
+
+It lints the spec first. A spec that fails lint, or is blocked on an open decision, runs no
+station and exits with lint's own code, because a draft cannot be checked against a spec that is
+not ready. Then it runs seven stations in a fixed order and prints one line for each: `pass`,
+`fail` with its findings, or `skip` with the reason. A warning prints under its station and never
+fails it. This is the essay example's draft:
+
+```
+form: pass
+terms: pass
+claims: pass
+quotes: pass
+private: pass
+dna: pass
+  warn [station-dna-drift] first_person_singular_rate is 22.892 in the draft; the scope's goldens measure 0, band 0 to 5
+    fix: Bring first_person_singular_rate back inside the band, or, if the scope no longer describes this writer, re-measure it with better goldens.
+links: pass
+verdict: one-shot
+```
+
+`--only form,terms` runs just those stations, still in the fixed order, and its ledger line is
+marked partial (see [The runs ledger](#the-runs-ledger)). `--json` prints the whole result, every
+finding included; a spec that is not ready prints lint's result with `lintBlocked: true` instead,
+and a usage error prints `{ "spec", "draft", "error" }`. A finding names the draft line it points
+at where there is one, quotes at most 80 characters of the draft, and never prints an absolute
+path. A UTF-8 byte order mark at the start of the draft is ignored.
+
+Exit codes: **0** every station that ran passed (a skip or a warning does not fail it); **1** a
+station failed; **2** usage: no spec path, no `--draft`, a draft that cannot be read, a spec
+without `profile: writing`, or an `--only` that names no known station; and lint's own **1** or
+**3** when the spec is not ready.
+
+Every station is a plain function of the spec and the draft. None of them calls a model, and none
+of them touches the network. What each one checks, and what it cannot:
+
+### form
+
+Counts the draft's words, by the same word definition `dna measure` uses, against
+`form.length`. Only `unit: words` is measured; any other unit skips the whole station rather than
+checking half of it. Every `required_parts` entry must appear as an ATX heading (`#` to
+`######`, indented at most three spaces, closing `#`s allowed) whose text equals the part,
+ignoring case, or as a line that starts with the part and a colon, for the fields a form fills in
+place (`To:`, `Subject:`). An underlined (Setext) heading does not count, and neither does
+anything inside a code block. It cannot tell whether the section under a heading does what the
+part is for, so write `required_parts` as the headings the piece will carry,
+as both examples do.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-form-length` | fail | the word count is outside `form.length`; the message gives the count and the range |
+| `station-form-required-part-<part>` | fail | a required part appears as neither a heading nor a `part:` line |
+
+### terms
+
+Reads the optional `audience.terms`: the words the piece uses that its reader may not know. For
+each term not also in `audience.knows`, it finds the term's first appearance (whole word, ignoring
+case) and looks for a definition in that sentence or the next: the term followed within six words
+by `is`, `means` or `refers to`, a colon among those words, or a parenthesis right after the term.
+This is a mechanical proxy for a definition, not a reading of one: "A hyperspec is mentioned here"
+passes. A term the draft never uses is not flagged, code blocks and inline code are ignored, and
+with no `terms` list the station skips.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-terms-undefined-<term>` | fail | the term's first appearance has no definition in that sentence or the next |
+
+### claims
+
+Reads the claims ledger at `sources.ledger`: JSONL, one claim per line, each with the claim's
+`text` exactly as the draft says it, a `source`, and optionally a `span`, the words in the source
+that support it. The examples cite a segment as the source, the same `material#segment` form the
+spine uses:
+
+```jsonl
+{"text":"11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status.","source":"survey#s4","span":"11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status."}
+```
+
+Every claim's text must still appear in the draft word for word, with whitespace and quote
+characters normalized and case kept; otherwise the ledger is stale. Every claim needs a real
+source; one without fails, or warns under `unsourced_claim: warn`. A missing ledger fails. The
+station does not decide what counts as a factual claim: the ledger is the list of claims, so a
+factual sentence left out of it passes unseen. Nor does it read the source to see whether it says
+what the claim says.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-claims-ledger-missing` | fail | the ledger file does not exist or cannot be read |
+| `station-claims-json-line-<n>` | fail | ledger line n is not JSON, not an object, or has no `text` |
+| `station-claims-stale` | fail | the claim on a ledger line no longer appears in the draft |
+| `station-claims-unsourced` | fail, or warn under `unsourced_claim: warn` | the claim on a ledger line has no source, or only a placeholder; points at the draft line where the claim appears |
+
+### quotes
+
+Every span in double quotation marks, straight or curly, of four words or more must appear word
+for word in a `quote` or `story` segment of a marked material. Quote characters and whitespace
+are normalized, case is kept, and a comma or period just inside the closing mark is dropped,
+because that punctuation is the writer's; a `?` or `!` is kept, because adding one changes what
+was said. Shorter spans are not checked, since two or three quoted words are as often a title as
+a quotation. A private segment is never a source for a quote. When the sentence around a quote
+names a speaker, the quote must come from a quote segment with that `speaker`. A speaker is named
+by the full `speaker` value, hyphens read as spaces, or by its first word, so `maria-lopez` is
+named by "Maria Lopez" and by "Maria". The first word alone counts only when it has two or more
+letters and is not a common function word such as "the", so a speaker recorded as "the manager
+interviewed" is named only by all three words. Attribution needs a declared speaker: a name that
+is no segment's `speaker` attributes nothing, so start a `speaker` with the person's name, as
+the essay example does with `dana, an engineering manager`. A spec with `fiction: true` skips
+the station: a character's dialogue is invented rather than quoted from a material, and a later
+release checks it against each character's own lines.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-quotes-unmatched` | fail | a quoted span is in no quote or story segment |
+| `station-quotes-misattributed` | fail | the sentence names a speaker, and the span is in no quote segment by that speaker |
+
+### private
+
+No run of eight or more consecutive words from any `private` segment may appear in the draft,
+compared by words with case and punctuation ignored. A private segment of four to seven words is
+checked whole. One under four words is not checked, because two or three words match ordinary
+prose; the station reports how many it skipped, as one warning that never quotes them. It cannot
+catch a paraphrase, or a leak shorter than the run.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-private-leak` | fail | the draft repeats a run from a private segment; names the material, the segment and the run |
+| `station-private-short-skipped` | warn | private segments under four words were not checked; gives the count |
+
+### dna
+
+Runs when `dna.scope_dir` is set and its `features.json` is current. It measures the draft the
+way `dna measure` measures goldens and compares the sentence length mean, both paragraph length
+means, every per-1000-word punctuation rate, and the contraction and person rates with the
+scope's. For a scope value v, a draft value outside v ÷ 1.5 to the larger of v × 1.5 and v + 5 is
+reported with both values. An em dash in a draft whose scope has none is its own finding,
+pointing at the first one. Both
+are warnings and the station never fails: it measures, and whether a draft sounds like its writer
+is a judgment. The essay's warning is an example of what to read: its goldens are instructions in
+the second person, and the essay tells the author's own story in the first. With no `scope_dir`,
+or a `features.json` that is missing or stale, the station skips and says which.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-dna-drift` | warn | a feature is outside its band; gives the draft's value, the scope's and the band |
+| `station-dna-em-dash` | warn | the draft uses em dashes and the scope's goldens use none |
+
+### links
+
+Every Markdown link (inline, reference, collapsed and shortcut) and every bare URL. An `http` or
+`https` URL must parse and name a host, a `mailto:` link must carry an address, and any other
+scheme fails. A relative link must resolve to a file, relative to the draft's own folder; the
+part after `#` is not checked. A link that starts with `/` is relative to a site root the station
+cannot see, so it warns. A full or collapsed reference, `[text][label]` or `[label][]`, needs a
+definition for its label. A bare `[label]` is a link only when that label has a definition;
+otherwise it is ordinary text, as Markdown renders it, so an editorial `[sic]`, a task list's
+`[x]` and a numbered note `[1]` pass. Code blocks and inline code are ignored. It never touches
+the network, so it cannot tell you a URL is live.
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-links-malformed` | fail | an http or https URL with no host (a bare `https://` included), or a `mailto:` with no address |
+| `station-links-bad-scheme` | fail | a scheme other than http, https or mailto |
+| `station-links-broken-relative` | fail | a relative link names no file beside the draft |
+| `station-links-root-relative` | warn | a link starting with `/`, which cannot be resolved without the site |
+| `station-links-undefined-reference` | fail | a full or collapsed reference link whose label has no definition |
+
+### Any station
+
+| Id | Severity | Meaning |
+|---|---|---|
+| `station-<name>-crashed` | fail | the station threw; the message is the error's, with any absolute path shortened; the other stations and the ledger line still run |
+
+### The runs ledger
+
+Each `check` appends one line to the spec's `improvement.ledger`, the same file lint's test 9
+reads:
+
+```json
+{"at":"2026-09-29T13:21:37.330Z","kind":"check","draft":"essay/draft.md","draft_sha256":"<sha256 of the draft>","spec_sha256":"<sha256 of the spec>","stations":{"form":"pass","terms":"pass","claims":"pass","quotes":"pass","private":"pass","dna":"pass","links":"pass"},"verdict":"one-shot"}
+```
+
+`draft` is the draft's path relative to the spec's folder, however you spelled it, so one draft
+has one history. `draft_sha256` and `spec_sha256` hash the two files' bytes; the files the spec
+names (materials, the claims ledger, a scope folder) are not hashed, so "changed" below means the
+draft or the spec. `stations` holds each station's status.
+
+A run with `--only` is partial: its line carries `partial: true`, its verdict is `not-improved`
+with the reason `partial run: <stations>`, and later verdicts ignore it, so a subset never claims
+the verdict for the whole draft. A full run is compared with the most recent earlier full line for
+the same draft:
+
+- **one-shot**: there is none, and every station passes.
+- **improved**: that line failed and every station passes now; `change` names exactly the
+  stations that failed then and pass now.
+- **not-improved** otherwise, with a `reason` that says which case it is: `failing stations: ...`
+  on a first check that fails; `no change since the last passing check`; `draft changed; every
+  station still passes` (or `spec changed`, or `spec and draft changed`); `still failing: ...`,
+  after `no change since the last check;` or after what changed, when every failing station failed
+  last time too; `failing stations: ...` after what changed when a station fails that passed last
+  time; and `stations that failed last time now skip: ...` when a spec change stopped them running.
+
+A ledger path that leads outside the spec's folder is not written, and `check` prints a warning.
+
 ## Deferring a block
 
 A block can be deferred, never silently missing. A required block that is absent fails test 1
@@ -849,13 +1072,19 @@ the field it needs, and every spine claim cites the segments that support it. Ea
 keeps the boundaries `segments init` wrote, in paragraph mode for prose and sentence mode for
 bulleted notes, so you can re-run it and compare.
 
-Both lint `pass (9/9)` with `writing: 9/9 blocks complete` and no findings. A test runs them on
-every release, so they cannot drift from the linter.
+Both lint `pass (9/9)` with `writing: 9/9 blocks complete` and no findings. Each also ships a
+draft written to it, `essay/draft.md` and `story/draft.md`, with its claims ledger beside it, and
+both drafts pass every station of `check`: the essay with one dna warning, described under
+[dna](#dna), and the story with dna skipped, since it names no scope folder, and quotes skipped,
+since it is fiction. A test lints both
+specs and checks both drafts on every release, so they cannot drift from the tool.
 
 ## What later versions add
 
-This release is the schema, its lint, marked materials, and scoped DNA with measured features.
-Later versions build on it in order. The first compares a draft against its scope: its features
-beside the scope's features, and a blind lineup in which a judge sees a generated passage among
-the scope's goldens and tries to pick it out. Then the stations themselves, running the checks
-each block names and grading drafts against the goal.
+This release is the schema, its lint, marked materials, scoped DNA, and `check` with seven
+deterministic stations. Next come the judgment stations: the simulated reader, the blind lineup,
+the persona judge and the doctor. hyperspec calls no model, so `check` will write each one as a
+packet, the draft and the rubric and the materials the judge needs, for an outside judge to fill
+in, and read the filled packet back as a station result. After that, a learn step that reads the
+runs ledger for the stations that keep failing and the changes that made them pass, so a fix
+lands in the spec or the skill that wrote the draft rather than in one draft.

package/bin/hyperspec.mjs

@@ -16,11 +16,25 @@ import { splitSegments } from "../src/segments.mjs";
 import { sha256 } from "../src/hash.mjs";
 import { readScope, measureFeatures, writeFeatures, scopeTemplate, GOLDENS_README } from "../src/dna.mjs";
 import { str } from "../src/placeholder.mjs";
+import { runCheck } from "../src/check.mjs";
 
 const HELP = `hyperspec <command> [options]
 
   lint <file...> [--json]      score each hyperspec against the nine tests
                                exit 0 pass, 1 a test fails, 3 blocked on an open decision, 2 usage
+  check <spec> --draft <file> [--json] [--only a,b]
+                               needs a writing spec (profile: writing); lints it first (a spec
+                               that does not pass lint, or is blocked, exits with lint's own code
+                               and runs no station: a draft cannot be checked against a spec that
+                               is not ready); then runs every deterministic station (or the
+                               --only subset, by name) against the draft, printing pass, fail
+                               (with findings) or skip (with a reason) per station; appends one
+                               line to the spec's improvement.ledger with a verdict: one-shot,
+                               improved, or not-improved with a reason (an --only run is partial:
+                               not-improved, and ignored by later verdicts)
+                               exit 0 every run station passed, 1 a station failed, 2 usage
+                               (including a missing draft file, a spec without the writing
+                               profile, or an --only that names no known station)
   init <file> [--title T] [--kind K]   write a new hyperspec skeleton (refuses to overwrite)
   init <file> --profile writing [--title T] [--form F] [--fiction]
                                write a writing-profile skeleton: every required block (materials,
@@ -282,6 +296,61 @@ if (cmd === "lint") {
   process.exit(worst);
 }
 
+if (cmd === "check") {
+  const parsed = parseArgs(argv.slice(1), { valueFlags: ["--draft", "--only"], boolFlags: ["--json"] });
+  if (parsed.error) { console.error(parsed.error); process.exit(2); }
+  const [specPath] = parsed.positionals;
+  const json = parsed.values["--json"];
+  // A usage error exits 2: a plain message on stderr, or under --json one document on stdout,
+  // { spec, draft, error }, the way lint --json reports a file it could not read.
+  const usage = (error) => {
+    if (json) console.log(JSON.stringify({ spec: specPath ?? null, draft: parsed.values["--draft"] ?? null, error }, null, 2));
+    else console.error(error);
+    process.exit(2);
+  };
+  if (!specPath) usage("check needs a spec path");
+  if (!parsed.values["--draft"]) usage("check needs --draft <file>");
+  let only;
+  if (parsed.values["--only"] !== undefined) {
+    only = parsed.values["--only"].split(",").map((s) => s.trim()).filter(Boolean);
+    if (!only.length) usage("--only names no station");
+  }
+
+  const result = runCheck(specPath, parsed.values["--draft"], { only });
+
+  // Usage errors (an unreadable spec, a spec without the writing profile, an unknown --only name,
+  // a missing draft file): exit 2, as above.
+  if (result.usage) usage(result.error);
+
+  if (result.lintBlocked) {
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else {
+      const r = result.lintScore;
+      console.log(`${result.specPath}: ${r.status} (${r.passed}/9)${r.open.length ? `, open: ${r.open.join(", ")}` : ""}`);
+      for (const t of r.tests) if (!t.pass) console.log(`  ✗ ${t.n}. ${t.name}`);
+      for (const f of result.lintFindings) console.log(`    ${f.severity === "fail" ? "fail" : "warn"} [${f.test}] ${f.message}\n         fix: ${f.fix}`);
+      console.log("no stations run: the spec is not ready (run `hyperspec lint` on it for details)");
+    }
+    process.exit(result.code);
+  }
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    for (const s of result.stations) {
+      if (s.status === "skip") { console.log(`${s.station}: skip (${s.reason})`); continue; }
+      console.log(`${s.station}: ${s.status}`);
+      for (const finding of s.findings) console.log(`  ${finding.severity === "fail" ? "fail" : "warn"} [${finding.id}] ${finding.message}${typeof finding.line === "number" ? ` (line ${finding.line})` : ""}\n    fix: ${finding.fix}`);
+    }
+    if (result.verdict) {
+      const detail = result.verdictDetail.change ?? result.verdictDetail.reason;
+      console.log(`verdict: ${result.verdict}${detail ? ` (${detail})` : ""}`);
+    }
+    if (result.ledgerWarning) console.log(`warn: ${result.ledgerWarning}`);
+  }
+  process.exit(result.code);
+}
+
 // Generic flag/positional parser for the recipe verbs below. A value-taking flag (valueFlags,
 // repeatableFlags) never swallows a following --flag as its value (missing value is an error, not
 // a silent grab); a bool flag never eats the next token as a positional; any --flag not declared

package/examples/writing/essay/claims.jsonl

@@ -0,0 +1,9 @@
+{"text":"29 of 41 people said their most useful one-on-one in the last quarter was one where they brought the first topic.","source":"survey#s3","span":"29 of 41 said their most useful one-on-one in the last quarter was one where they brought the first topic."}
+{"text":"That is how an engineering manager I interviewed, eight years into the job, runs hers.","source":"interview#s4","span":"She keeps a shared document per person; they add items before the meeting, and she adds hers last, at the bottom."}
+{"text":"Her rule is short: the report owns the agenda.","source":"interview#s3","span":"Her rule: the report owns the agenda."}
+{"text":"My first one-on-one as a manager was a disaster, and the reason was simple: I ran it.","source":"voice-memo#s2","span":"My first one-on-one as a manager was a disaster, and the reason was simple: I ran it."}
+{"text":"11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status.","source":"survey#s4","span":"11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status."}
+{"text":"What is taking more of your energy than it should?","source":"voice-memo#s4","span":"What is taking more of your energy than it should?"}
+{"text":"What do you want to be doing more of in six months?","source":"voice-memo#s4","span":"What do you want to be doing more of in six months?"}
+{"text":"What should I stop doing, or start doing, that would make your week easier?","source":"voice-memo#s4","span":"What should I stop doing, or start doing, that would make your week easier?"}
+{"text":"The most common free-text request in the survey, in 9 responses, was to be asked what they want to work on next.","source":"survey#s5","span":"The most common free-text request, in 9 responses: \"ask me what I want to work on next.\""}

package/examples/writing/essay/draft.md

@@ -0,0 +1,82 @@
+# Hand your first one-on-one to the person you manage
+
+## Who sets the agenda
+
+Your first one-on-one with a new report is the only meeting on your calendar where they should
+set the agenda. Everything else you run. This one you hand over.
+
+If you walk in with a list, you have told your report what the meeting is for, and it is for
+you. They will answer your list politely and leave. You will know nothing you did not know when
+you sat down, and so will they.
+
+My team ran a [survey](materials/team-survey.md) this spring. 29 of 41 people said their most useful one-on-one in the last
+quarter was one where they brought the first topic. The meeting that worked for them was the one
+they started.
+
+So give them the start. The simplest way to do it is a running agenda: one shared document per
+person, kept for as long as you manage them. Your report adds items before each meeting, and you
+add yours last, at the bottom. That is how an engineering manager I interviewed, eight years into
+the job, runs hers. Her rule is short: the report owns the agenda.
+
+## My first one-on-one
+
+My first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a
+list, and I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes
+later my report said thanks and left, and I had learned nothing I could not have read in the
+tracker.
+
+What I ran was a status meeting, which is a meeting spent reading out loud what the tracker
+already says. Your report wrote those updates. Asking them to recite the updates to you teaches
+you nothing new, and it spends the one half hour a week that belongs to them.
+
+The survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the
+last quarter was mostly project status. Read the tracker before you walk in, and leave status
+there.
+
+## The three questions
+
+Here is what I ask now, in this order, and then I let the report take over:
+
+1. What is taking more of your energy than it should?
+2. What do you want to be doing more of in six months?
+3. What should I stop doing, or start doing, that would make your week easier?
+
+Three is enough to hand the meeting over. The first asks about this week. The second asks about
+the next six months. The third asks about you, and it is the one your report will not raise
+without being asked. A fourth question starts to look like your list again, and the list is what
+you came to give up.
+
+Ask them in the same words every time. Your report will learn them, and after a few weeks they
+will walk in with answers already half formed. That is the point of fixing the words: the meeting
+starts on their topic before you have said anything at all.
+
+The second question is the one my own team asked for. The most common free-text request in the
+survey, in 9 responses, was to be asked what they want to work on next.
+
+After the third question, stop talking.
+
+## What to do with the answers
+
+Wait after each question, longer than you want to. Dana, the engineering manager I interviewed,
+puts it in three short sentences: "Wait. Count to five. The real answer is the second one." The first
+answer your report gives is the tidy one, the version they could give anyone. The second is what
+they came in with, and you only hear it if you let the silence run.
+
+Write down what they say, in their words, at the top of the running agenda. That list is where
+your next one-on-one starts, so the meeting stays theirs the week after too.
+
+Do not try to fix everything in the room. Pick one thing you can act on this week, say what you
+will do, and do it before you meet again. The rest stays on the running agenda until it is done
+or your report takes it off.
+
+And keep your own urgent items out of it. She told me: "If I have something urgent, it is not a
+one-on-one topic. I send it the day it happens." Your report should never have to wait a week to
+hear something you needed them to know on Monday.
+
+## Before the meeting
+
+Open the invite and delete your list from it. Ask your report to add the first item to the
+running agenda instead.
+
+So write the three questions on a card. Ask the first one. Then wait, longer than feels polite,
+because the first answer is the one they rehearsed and the second one is the one you came for.