@supersuit/hyperspec 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 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,6 +24,7 @@ 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 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. |
@@ -103,11 +104,39 @@ 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.
+
 ## 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.3, the writing profile included, and cut 0.4 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.3.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,7 +216,7 @@ 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 |
 
@@ -233,6 +239,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, and `hyperspec init --profile writing` 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 +258,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 +273,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
 }

package/WRITING.md

@@ -0,0 +1,426 @@
+# The writing profile
+
+A hyperspec for a piece of writing. An essay, a chapter, a letter, a story: anything an agent
+drafts and a person reads.
+
+Writing is where the average does the most damage. Asked for "an essay on X", an agent fills
+every gap you left with the most typical choice: the typical reader, the typical argument, the
+typical voice. Each choice is reasonable and the sum reads like nobody in particular wrote it.
+The writing profile names the gaps a piece of writing has, so each one is filled on purpose, by
+someone you can name, and checked before a draft reaches you.
+
+A profile adds rules for one kind of work without adding a test. Every writing finding reports
+under one of the nine tests in [SPEC.md](SPEC.md), with an id that starts `writing-`, and the
+score is still out of nine. Everything in the core format (decisions, requirements, rejects,
+examples, resume, feedback, improvement) still applies and is still linted.
+
+## Opting in
+
+Add `profile: writing` at the top level of the frontmatter, and a `writing:` map holding the
+blocks. `hyperspec lint` then prints one more line under the score:
+
+```
+essay.hyperspec.md: pass (9/9)
+  writing: 9/9 blocks complete
+```
+
+A block counts as complete when it is present with no failing finding. `characters` also counts
+as complete when the piece is not fiction, since nothing requires it. A block deferred to a
+decision (see [Deferring a block](#deferring-a-block)) does not count as complete, because
+nothing has been written in it yet. `--json` carries the same count on each file as
+`"profile": { "name": "writing", "complete": 9, "total": 9 }`.
+
+A `profile:` this linter does not know is a warning under test 7, naming the profile and saying
+its rules were not checked.
+
+## The ten components
+
+These are the parts you cannot remove without the writing sliding back to the middle. Nine are
+blocks under `writing:`. The tenth, progress, is deliberately never written down.
+
+### 1. Materials: what goes in, and how it is marked
+
+Brain dumps, transcripts, interview answers, notes, prior pieces, research. Each material
+records who produced it, when it was captured, how, and how far it can be trusted: `raw` for
+thinking out loud, `considered` for something someone has reviewed, `verified` for something
+checked against its source. A brain dump is the most valuable input and the least structured, so
+marking it is the step that turns thinking into something an agent can cite. Each material is
+split into segments and each segment gets a label saying what it may be used as (see
+[Materials labels](#materials-labels)).
+
+### 2. Writer DNA: who is writing, and how they sound, for this purpose
+
+A writer does not have one voice. The same person writes differently for a theology journal and
+a landing page, so their DNA is scoped by **form, audience and purpose**, and the scope is the
+whole design of this block.
+
+- **Rules** are the one layer that applies everywhere: what the writer never does and always
+  does. They live in your style rules file, and every piece in every scope points at it.
+- **Goldens** are real passages the writer has marked as right, each filed under its scope. A
+  golden feeds only work that shares that scope, so a sermon golden can never leak into a sales
+  email.
+- **Every golden carries a note on why it is golden.** A golden without its reason teaches the
+  surface; the reason teaches the move.
+
+DNA is proven by a blind lineup within its scope: a judge sees a generated passage beside real
+goldens of the same kind and tries to pick it out. Every writer has their own DNA, and nobody's
+scope feeds anybody else's.
+
+### 3. Persona: who the piece speaks as
+
+The identity the piece speaks as (the writer as themselves, a role, or a character), its stance
+toward the reader, what it may assert, and what it will not say. Research on persona prompting
+finds that a persona shapes voice and alignment and can cost accuracy
+([PRISM](https://arxiv.org/html/2603.18507v1)), so here the persona governs voice and stance only.
+**Facts come from marked sources, never from the persona.** That separation is a field,
+`facts_from: sources`, and the linter refuses any other value.
+
+The persona is recorded in the spec, where it belongs. The piece itself says nothing to the
+reader about who is writing.
+
+### 4. Audience: who is reading
+
+A named person or a specified archetype: where they are on their path right now, which words
+they already have, what they believe now, what they want, where they will read it (a phone in
+ninety seconds, aloud, in print), and whether the reader is a person or another agent. Checked
+by a term station (every word outside their vocabulary is defined on first use) and by a
+simulated reader, a model playing that exact reader, which reports where it got lost and where
+it would have stopped.
+
+### 5. Goal: what the piece changes
+
+The one step down the funnel: where this reader is now, where the piece moves them, and what
+they do next if it worked. Then the change that step needs in them (a belief, an action or a
+feeling), and five to ten requirements that would prove it happened, each written to be failable.
+This is the block a grader works against, and the simulated reader is asked the one question that
+matters: would you take the next step now?
+
+### 6. Form: what kind of thing it is
+
+Essay, chapter, wiki article, email, text, talk, letter, story. A form supplies its required
+parts, its length envelope, and any extra checks it needs: a chapter checks continuity with the
+chapters around it, a wiki article checks its links, a text message checks bubble length.
+
+### 7. Spine: what it argues
+
+The kind of argument (thesis, testimony, primer, letter, story; the set is open) and the claim
+chain: the three to seven claims the piece has to land, in order, each pointing at the materials
+that support it.
+
+### 8. Sources and claims: what lets another agent pick it up
+
+A claims ledger beside the piece: every factual claim in the draft points at a source and the
+span in it, and every quote is matched word for word against its source. A writer's own brain
+dump counts as a source for their opinions and their stories, never for an outside fact. By
+default a claim with no source fails the check rather than passing with a warning.
+
+### 9. Characters: everyone who speaks inside the work
+
+The persona is who the piece speaks as. A character is someone who speaks inside it, and the
+same rules apply one level down. Required when `fiction: true`. Each character carries:
+
+- **Speech DNA**: the words they use, the ones they never would, and their rhythm.
+- **Wants, fears, and the thing they hide**, because dialogue is someone trying to get something
+  while hiding something.
+- **What they know, and when.** A knowledge timeline by chapter or scene, so a character never
+  says what they could not know yet. This is the most common way generated dialogue breaks a
+  story, and it is fully checkable.
+- **How they speak to each person that matters**, since speech shifts by relationship.
+- **Arc state**: where they are in their change at this point in the work.
+- **Golden lines and rejected lines**: real lines that sound exactly like them, and lines that
+  sound close but wrong.
+
+Checked by a blind attribution test (a judge sees a line with the speaker hidden and has to name
+who said it), a knowledge-leak check against the timeline, and a consistency check against the
+golden and rejected lines. If your characters already live as entities in a world database, the
+optional `entity` field points at that record, so one record can say how a character looks and
+how they speak.
+
+### 10. Progress: where it is
+
+Derived from disk, never stored. Which blocks are filled, which drafts exist, which checks
+passed, what the last review said, and the next action are all things a second agent can read
+off the folder itself. A saved progress field goes stale the first time a session dies mid-arc,
+and from then on it lies to every agent that trusts it. So the linter refuses one: a
+`writing.progress` key fails test 7, and `resume.next_action` stays the only thing the spec
+says about what happens next.
+
+## The schema
+
+Every field below is required unless its comment says otherwise, and a required list needs at
+least one entry. A path resolves relative to the spec file, the same way `examples` does, and a
+path the linter checks must name a file that exists.
+
+```yaml
+profile: writing
+fiction: false                       # optional, true or false; absent means false. true requires writing.characters
+writing:
+  materials:
+    items:                           # at least one
+      - id: voice-memo               # unique across items
+        path: materials/voice-memo.md
+        produced_by: example-author
+        captured: "2026-09-12"
+        how: voice memo, transcribed
+        trust: raw                   # raw | considered | verified
+    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: essay
+      audience: new managers
+      purpose: teach
+    rules: style-rules.md            # your style rules file, the always-on layer
+    goldens:                         # at least one
+      - path: goldens/opening.md
+        why: one plain claim, then a second sentence that turns it into something to do
+    check:
+      rubric: blind lineup within this scope
+    source: goldens marked on the review page
+    author: example-author
+  persona:
+    identity: self                   # self | role:<name> | character:<id>
+    stance: mentor                   # peer | mentor | witness | guide; anything else warns
+    may_assert:
+      - what the author did in their own first one-on-ones
+    will_not_say:
+      - the name of anyone on the author's team
+    facts_from: sources              # must be exactly "sources"
+    check:
+      rubric: persona-consistency judge
+    source: persona interview
+    author: example-author
+  audience:
+    who: someone in their first three months of managing
+    funnel_now: has a first one-on-one on the calendar this week
+    knows:
+      - one-on-one
+      - report
+    believes_now: a one-on-one is where a manager catches up on the work
+    wants: a plan for the first meeting
+    reads_on: a phone, in the ten minutes before the meeting
+    reader: person                   # person | agent
+    check:
+      station: term check against knows
+      rubric: simulated reader reports where it got lost
+    source: audience interview
+    author: example-author
+  goal:
+    from: plans to run the meeting from their own list
+    to: hands the meeting to the report
+    next_if_worked: copies the three questions into the invite
+    change:
+      kind: action                   # belief | action | feeling
+      text: the reader asks the three questions and waits
+    conditions:                      # 5 to 10 distinct ids of top-level requirements, each once
+      - r1
+      - r2
+      - r3
+      - r4
+      - r5
+    check:
+      rubric: grade the draft against every condition
+    source: goal interview
+    author: example-author
+  form:
+    name: essay                      # open set
+    length:                          # whole numbers, at least 1, min no more than max
+      min: 700
+      max: 1100
+      unit: words
+    required_parts:
+      - an opening that states the claim
+      - the three questions
+      - a close
+    stations:                        # may be empty
+      - the three questions render as a numbered list
+    check:
+      station: structure and length check
+    source: form decision
+    author: example-author
+  spine:
+    kind: primer                     # open set
+    claims:                          # 3 to 7, in order, each with its own id
+      - id: c1
+        text: the first one-on-one is the one meeting the report should set the agenda for
+        materials:                   # ids from materials.items; voice-memo#segment is accepted
+          - voice-memo
+      - id: c2
+        text: status belongs in the tracker
+        materials:
+          - voice-memo
+      - id: c3
+        text: three questions are enough to hand the meeting over
+        materials:
+          - voice-memo
+    check:
+      rubric: each claim lands, in order, and nothing is argued outside the chain
+    source: spine interview
+    author: example-author
+  sources:
+    ledger: claims.jsonl             # need not exist before drafting
+    unsourced_claim: fail            # fail | warn; warn is reported as a warning
+    check:
+      station: every factual claim points at a source span
+    source: sourcing pass
+    author: agent:claude
+  characters:                        # required when fiction: true; ids unique
+    - id: ines
+      entity: world/ines.json        # optional; if given, the file must exist
+      speech:
+        uses:
+          - instructions in the imperative
+        never:
+          - an apology in words
+        rhythm: short, flat sentences # optional
+      wants: to leave the bakery in hands she trusts
+      fears: that he will stay in a trade with no bakery to do it in
+      hides: that she sold the bakery two weeks ago
+      knowledge:                     # at least one; each entry needs by and knows
+        - by: scene-1
+          knows: the sale closes on Friday
+      relationships:                 # optional
+        - to: theo
+          how: gives him instructions where another person would give praise
+      arc_state: has let go of the bakery, and has not yet let go of him
+      golden_lines:                  # at least one
+        - Flour first. Then you can talk.
+      rejected_lines:                # at least one, and none of them also golden
+        - I'm so sorry I didn't tell you sooner.
+      check:
+        rubric: blind attribution test, knowledge-leak check, consistency against golden and rejected lines
+      source: notes.md
+      author: example-author
+```
+
+Every block, and every character, carries `check` (with `station:` for a deterministic check or
+`rubric:` for what a grader applies, the same shape a requirement's check has), `source` and
+`author`. `characters` is a list, so there each entry carries its own.
+
+Write every map in block style, one key per line, as above. The YAML reader hyperspec uses reads
+a flow list such as `[r1, r2]`, but it reads an inline map such as `{ station: ... }` as a plain
+string, and a flow list followed by a comment on the same line as a string too.
+
+A placeholder counts as missing, here and everywhere else in a hyperspec, so a scaffolded field
+cannot pass a presence check. 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, such as `TODO: write the opening`, counts as present, and so does `none`.
+
+## The test mapping
+
+Each row lists what the writing profile adds to that test. The core conditions in
+[SPEC.md](SPEC.md#the-test-to-field-map) still apply alongside them.
+
+| 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 `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` |
+| 5 negative space is specified | `persona.will_not_say` is empty; `persona.facts_from` is anything other than `sources` |
+| 6 examples outrank adjectives | a golden has no `why`; a material, `dna.rules`, golden or character `entity` path does not exist or is not a file; a character has no golden lines or no rejected lines, or has the same line in both (compared trimmed and case-folded) |
+| 7 a stranger can resume it | `writing.progress` exists. An unknown `profile:` is a warning |
+| 8 its adopters can push back on it | nothing further; the core rule applies |
+| 9 it improves itself | nothing further; the core rule applies |
+
+## Closed sets
+
+| Field | Allowed values |
+|---|---|
+| `materials.items[].trust` | `raw`, `considered`, `verified` |
+| `persona.identity` | `self`, `role:<name>`, `character:<id>` |
+| `persona.stance` | `peer`, `mentor`, `witness`, `guide`; any other value warns |
+| `persona.facts_from` | `sources` |
+| `audience.reader` | `person`, `agent` |
+| `goal.change.kind` | `belief`, `action`, `feeling` |
+| `sources.unsourced_claim` | `fail`, `warn` |
+| `fiction` | `true`, `false`; absent means `false` |
+
+`form.name` and `spine.kind` are open: name the form and the kind of argument in your own words.
+
+## Materials labels
+
+Before a material is used, it is split into segments, and each segment gets one of seven labels.
+The label decides what the segment may become in the draft.
+
+| Label | Means | May be used as |
+|---|---|---|
+| `claim` | a statement of fact about the world | only with a source, or as the author's own claim said as such |
+| `story` | something that happened, told by someone who was there | testimony, with the teller named |
+| `quote` | words someone said, verbatim | quoted exactly, never paraphrased inside quotation marks |
+| `stance` | an opinion or conviction | the author's position |
+| `question` | something open | a prompt for the interview, never an assertion |
+| `aside` | true but off the thread | held back unless the spine needs it |
+| `private` | not for this audience | never used; kept for context |
+
+The linter defines the set once, as `MATERIAL_LABELS` in `src/writing.mjs`. This release checks
+the materials list itself; it does not yet read segment files or check their labels. A spine
+claim may point at a segment as `m1#segment`, and today only the material id before the `#` is
+checked.
+
+## Deferring a block
+
+A block can be deferred, never silently missing. A required block that is absent fails test 1
+unless a decision with the id `writing-<block>` stands in for it:
+
+```yaml
+decisions:
+  - id: writing-audience
+    state: open
+    question: who reads this, and what do they already believe?
+    source: kickoff call
+    author: agent:claude
+    chosen_by: agent
+```
+
+- **`open`** defers the block to a question only a person can answer. The spec is blocked on it,
+  exactly like any open decision: `lint` exits 3 once every test passes.
+- **`delegated` with a `rule`** defers the block to a standing rule the agent follows. The spec
+  can pass. A delegated decision with no `rule` defers nothing, so the missing block still fails.
+
+Either way the deferred block does not count toward `writing: k/9 blocks complete`.
+
+## Starting a writing spec
+
+```bash
+npx @supersuit/hyperspec init essay.hyperspec.md --profile writing --title "Your title" --form essay
+npx @supersuit/hyperspec init story.hyperspec.md --profile writing --form "short story" --fiction
+```
+
+The skeleton shows every required block in schema order with every field present as a `TODO`
+placeholder. `dna`, `persona`, `audience` and `goal` also carry an open decision whose question
+says what you have to answer before the placeholder means anything. `--form` sets both `kind:`
+and `writing.form.name`, and defaults to `essay`. `--fiction` sets `fiction: true` and adds one
+character with the same treatment. The skeleton never passes: it lints `fail`, with
+`writing: 1/9 blocks complete` (or `0/9` with `--fiction`), until the placeholders and the open
+decisions are replaced with real content.
+
+`init` refuses, with exit 2 and a plain message, anything it would otherwise have to ignore:
+`--profile` with no value or one this linter does not know, `--fiction` or `--form` without
+`--profile writing`, `--kind` with it (the form sets the kind), and a file in a folder that does
+not exist.
+
+## Worked examples
+
+Two complete specs ship in [`examples/writing/`](examples/writing/), each with every file it
+names:
+
+- `essay.hyperspec.md`: an essay for new managers on running a first one-on-one. Three materials
+  at three trust levels, scoped DNA with two annotated goldens, a four-claim spine.
+- `story.hyperspec.md`: a short story, `fiction: true`, narrated by one of its two characters.
+  Each character has speech rules, a knowledge timeline by scene, and golden and rejected lines
+  in a voice you can tell apart from the other's.
+
+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.
+
+## What later versions add
+
+This release is the schema and its lint. Later versions build on it in order: marking materials
+(a brain dump or transcript in, labeled segments out, with the labels above enforced), scoped
+DNA with annotated goldens filed by form, audience and purpose, and the stations themselves,
+running the checks each block names and grading drafts against the goal.