@supersuit/hyperspec 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.1.0 (2026-09-28)
+
+- The hyperspecification standard: a markdown file with a YAML frontmatter block, versioned
+  in git, living beside the work it specifies.
+- Nine tests: decisions, failable requirements, checked requirements, provenance, rejects,
+  examples, resumability, a place to push back, and an improvement ledger.
+- `hyperspec lint <file...> [--json]`, exiting 0 pass, 1 a test fails, 3 blocked on an open
+  decision, 2 usage or IO error.
+- `hyperspec init <file> [--title T] [--kind K]`, writing a new hyperspec skeleton and
+  refusing to overwrite an existing file.
+- Every finding names its test, a severity, a message and a fix.
+- YAML read only through `parseSkillFile` from `@supersuit/superskill/yaml`.
+- SPEC.md is itself a hyperspec and passes its own lint.
+- A placeholder value never counts as present: a value that is only a YAML comment
+  (`source: # TODO`), or `null`, or `~`, fails the test its field belongs to.
+- `hyperspec lint` never skips a file that follows a stray flag such as `--kind`.
+- The package ships `examples/minimal.hyperspec.md`, the smallest spec that passes all nine
+  tests, and SPEC.md points at it, so the SPEC.md inside the package passes its own lint.
+- Test 7 fails a `next_action` that is only a no-action word (`continue`, `tbd`, `n/a`, and
+  the rest), so "continue drafting section two from the outline" passes; it also fails a
+  `next_action` that says "as discussed" or "as mentioned earlier" or "above".
+- Test 5 names a `rejects` item that is not a plain string, instead of reporting that
+  nothing is rejected.
+- SPEC.md describes exactly what `lint` enforces: decision completeness is the author's job,
+  a vague `fails_when` is a warning, where `chosen_by` is checked, how example paths
+  resolve, and that exit 2 covers a file that is not a hyperspec.
+- A ledger can never crash the linter: a ledger path that is a directory or a device, or a
+  file that cannot be read, fails test 9, and a ledger line that is valid JSON but not an
+  object (such as `null`) is a bad line. A crash on one file is reported as that file's
+  error and never stops the others or empties `--json`.
+- The body scan for "as discussed" skips fenced code blocks and inline code, so a spec can
+  quote the phrases it bans. SPEC.md lints with zero findings, warnings included.
+- SPEC.md cites only sources a public reader can open, and its next action is to collect
+  adopter issues on 0.1 and cut 0.2 from them.
+- The README's sample output is exactly what `hyperspec lint` prints.
+- Reads YAML through `@supersuit/superskill/yaml` 0.2.1, which now returns a comment-only value
+  (`source: # TODO`) as an empty string itself. The placeholder rule no longer treats a leading
+  `#` as empty; it only handles `null` and `~`, which the reader still keeps as those literal
+  strings. A quoted value that starts with `#` (`source: "# literal"`) is real text and counts
+  as present.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SupersuitUp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# hyperspec
+
+A hyperspec is a spec written for an agent: every decision is recorded with who made it and
+where it came from, every requirement can fail in a named way, and every field is traced back
+to its source. This package is the standard and its linter.
+
+## 30 seconds
+
+```bash
+npx @supersuit/hyperspec lint spec.md
+```
+
+```
+spec.md: pass (9/9)
+```
+
+Nine tests run against the frontmatter: decisions, failable requirements, checked
+requirements, provenance, rejects, examples, resumability, a place to push back, and an
+improvement ledger. Every test is defined in [SPEC.md](SPEC.md).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `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. |
+
+## Exit codes
+
+`hyperspec lint` exits 0 when every test passes and nothing is open, 1 when at least one
+test fails, 2 on a usage or IO error, and 3 when every test passes but a decision is still
+open (blocked).
+
+## 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).
+
+## Install
+
+```bash
+npm install @supersuit/hyperspec
+```
+
+Node 20 or later. One dependency, `@supersuit/superskill`, for the YAML reader.

package/SPEC.md

@@ -0,0 +1,190 @@
+---
+hyperspec: "0.1"
+title: The hyperspecification standard
+kind: standard
+decisions:
+  - id: format
+    state: decided
+    value: a hyperspec is a markdown file with a YAML frontmatter block, versioned in git, living beside the work it specifies
+    source: SPEC.md, section "The format (what `lint` reads)"
+    author: gary-sheng
+    chosen_by: human
+  - id: yaml-reader
+    state: decided
+    value: hyperspec reads YAML only through parseSkillFile from @supersuit/superskill/yaml; it never carries a second parser
+    source: "superskill 0.2.0 CHANGELOG: the reader gained nesting so standards in this family import it instead of writing a second parser"
+    author: gary-sheng
+    chosen_by: human
+  - id: exit-codes
+    state: decided
+    value: "0 every test passes and nothing is open; 1 at least one test fails; 3 every test passes but a decision is open; 2 usage or IO error"
+    source: SPEC.md, section "Exit codes", and README.md, section "Exit codes"
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: lint exits 0 only when all nine tests pass and nothing is open
+    fails_when: a spec missing fails_when on any requirement exits 0
+    check:
+      station: test/rules.test.mjs and test/score.test.mjs
+    source: SPEC.md, section "What makes a spec a hyperspec"
+    author: gary-sheng
+  - id: r2
+    text: every finding names a fix
+    fails_when: a finding with an empty fix
+    check:
+      station: "test/rules.test.mjs, \"every finding names its test\""
+    source: CHANGELOG.md, 0.1.0, "every finding names its test, a severity, a message and a fix"
+    author: agent:claude
+rejects:
+  - prose advice where a field could be checked
+  - a second YAML parser
+examples:
+  - path: examples/minimal.hyperspec.md
+    why: the smallest spec that passes all nine tests
+resume:
+  next_action: collect adopter issues on 0.1 and cut 0.2 from them
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes and say so in your SPEC
+improvement:
+  ledger: runs.jsonl
+---
+
+# The hyperspecification standard
+
+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.1.0** (2026-09-28)
+
+## What makes a spec a hyperspec
+
+A spec is a hyperspec when it passes these nine tests. Each one is checkable, which is itself the first test.
+
+### 1. every decision is accounted for
+
+The form of the work has a known list of decision points: for an essay, who it is for, what it argues, how it opens, how long it runs, what it refuses to say, and so on. Each one is decided, delegated with the rule the agent uses to decide it, or open. An open decision stops the work. Nothing is left to the average.
+
+`lint` checks that at least one decision is listed and that each listed decision is well-formed. Whether the list covers every decision the form of the work has is the author's job, because the linter does not know the form's full list.
+
+### 2. every requirement can fail
+
+Each line is written so a specific observation could show it was not met, under `fails_when`. The observation is what makes a requirement failable. "A reader who has never heard the term can say what it means after the first section" is one. A vague word such as "engaging" in `fails_when` is reported as a warning, because it leans on an adjective where an observation should be.
+
+### 3. every requirement names its check
+
+Either a deterministic station (a lint, a schema, a source match) or a judgment station (a rubric a grader applies), and the check is written beside the requirement it belongs to.
+
+### 4. every field says where it came from and who wrote it
+
+Where: a brain dump line, an interview answer, a transcript, a prior piece. Who: a person or an agent, and which one, and whether a human explicitly chose it or an agent proposed it and nobody objected. `lint` checks `source`, `author` and `chosen_by` on every decision, and `source` and `author` on every requirement. Neither answer is bad on its own. Knowing which is what lets you debug: an agent that invented a detail, or a person who put in something wrong, both show up as a field with an author you can ask.
+
+### 5. negative space is specified
+
+What the work must not do is usually more specific than what it must do. A hyperspec lists its rejected poles under `rejects`.
+
+### 6. examples outrank adjectives
+
+Where a quality matters, the spec points at a real example of it instead of describing it. A model copies surface style from a description and misses the style an example carries.
+
+### 7. a stranger can resume it
+
+A different agent, with only the spec and the state beside it, can pick the work up mid-flight and know what to do next. The spec is the primary artifact, and the output is regenerable from it.
+
+### 8. its adopters can push back on it
+
+A spec receives issues and pull requests, like code. Anyone adopting it can say they are not happy with it, propose a change, and fork it for their own purposes. A spec nobody can argue with stops improving the day it ships.
+
+### 9. it improves itself
+
+Every run leaves a verdict: it went through clean, or it did not and the spec or the skill changed, or it did not and here is why nothing changed. A framework with no improvement loop is as good on its first run as it will ever be.
+
+## The format (what `lint` reads)
+
+A hyperspec is a markdown file with a YAML frontmatter block. This is the shape:
+
+```yaml
+---
+hyperspec: "0.1"
+title: What this specifies
+kind: essay
+decisions:
+  - id: audience
+    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>
+    chosen_by: human          # human | agent
+  - id: length
+    state: delegated
+    rule: as short as the claim chain allows, never over 1,200 words
+    source: design doc, Part 2
+    author: agent:claude
+    chosen_by: agent
+  - id: title
+    state: open
+    question: which of the three candidate titles?
+    source: draft 2
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: a reader new to the term can say what it means after section one
+    fails_when: the simulated reader cannot define the term after section one
+    check:
+      rubric: ask the simulated reader to define the term; pass only on a correct definition
+    source: design doc, audience block
+    author: gary-sheng
+rejects:
+  - hype words about AI
+examples:
+  - path: goldens/opening.md
+    why: the claim lands in the first line and the second line earns it
+resume:
+  next_action: write the outline from the claim chain
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: runs.jsonl
+---
+```
+
+## 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.
+
+| Test | Fails when |
+|---|---|
+| 1 every decision is accounted for | no `decisions`; a decision with no or duplicate `id`; `state` not decided, delegated or open; decided without `value`; delegated without `rule`; open without `question` |
+| 2 every requirement can fail | no `requirements`; a requirement without `text` or without `fails_when`. A vague word in `fails_when` is a warning |
+| 3 every requirement names its check | a requirement whose `check` has neither `station` nor `rubric` |
+| 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, 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 |
+| 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` |
+
+## Exit codes
+
+`hyperspec lint` reports the worst result across every file it is given:
+
+- **0** every test passes and nothing is open.
+- **1** at least one test fails.
+- **3** every test passes, but a decision is left open, so the work waits on that decision.
+- **2** usage error; a file that could not be read; a file whose frontmatter is missing or broken; or a file that is not a hyperspec. A file is a hyperspec when its frontmatter has a `hyperspec` key.
+
+## The improvement ledger
+
+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.
+- **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.
+
+## Why now
+
+A human reader treats a thousand-line spec as a burden, so specs were written short and the gaps were filled from shared context. A model reads all of it at almost no cost and uses every line. Detail that would have been waste between two people is now the cheapest input there is. That is the whole reason hyperspecification exists now and could not have before: the reader changed, so the economics of writing everything down changed with it.

package/bin/hyperspec.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { existsSync, writeFileSync } from "node:fs";
+import { loadSpec } from "../src/load.mjs";
+import { lintSpec } from "../src/rules.mjs";
+import { score, exitCode } from "../src/score.mjs";
+import { template } from "../src/template.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
+  init <file> [--title T] [--kind K]   write a new hyperspec skeleton (refuses to overwrite)
+
+Spec: SPEC.md`;
+
+const argv = process.argv.slice(2);
+const flag = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+const cmd = argv[0];
+
+if (!cmd || cmd === "--help" || cmd === "-h") { console.log(HELP); process.exit(cmd ? 0 : 2); }
+
+if (cmd === "init") {
+  const file = argv[1];
+  if (!file || file.startsWith("--")) { console.error("init needs a file path"); process.exit(2); }
+  if (existsSync(file)) { console.error(`refusing to overwrite ${file}`); process.exit(2); }
+  writeFileSync(file, template({ title: flag("--title"), kind: flag("--kind") }));
+  console.log(`wrote ${file}; run: hyperspec lint ${file}`);
+  process.exit(0);
+}
+
+if (cmd === "lint") {
+  const json = argv.includes("--json");
+  // Lint takes one flag, --json, and no flag takes a value, so a flag is dropped on its own and
+  // never takes the argument after it (a stray --kind before the files must not swallow one).
+  const files = argv.slice(1).filter((a) => !a.startsWith("--"));
+  if (!files.length) { console.error("lint needs at least one file"); process.exit(2); }
+  const rank = { 2: 4, 1: 3, 3: 2, 0: 1 };
+  let worst = 0;
+  const reports = files.map((file) => {
+    const spec = loadSpec(file);
+    if (spec.error) { worst = 2; return { file, status: "error", error: spec.error }; }
+    // A crash on one file is reported as that file's error; it never aborts the others or empties --json.
+    let findings, s;
+    try { findings = lintSpec(spec); s = score(findings, spec.data); }
+    catch (e) { worst = 2; return { file, status: "error", error: `lint crashed: ${e.message}` }; }
+    const code = exitCode(s.status);
+    if (rank[code] > rank[worst]) worst = code;
+    return { file, ...s, findings };
+  });
+  if (json) console.log(JSON.stringify({ files: reports }, null, 2));
+  else for (const r of reports) {
+    if (r.error) { console.log(`${r.file}: ${r.error}`); continue; }
+    console.log(`${r.file}: ${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 r.findings) console.log(`    ${f.severity === "fail" ? "fail" : "warn"} [${f.test}] ${f.message}\n         fix: ${f.fix}`);
+  }
+  process.exit(worst);
+}
+
+console.error(`unknown command: ${cmd}\n\n${HELP}`);
+process.exit(2);

package/examples/goldens/opening.md

@@ -0,0 +1 @@
+The claim first.

package/examples/minimal.hyperspec.md

@@ -0,0 +1,39 @@
+---
+hyperspec: "0.1"
+title: What this specifies
+kind: essay
+decisions:
+  - id: audience
+    state: decided
+    value: the operator, reading on a phone
+    source: interview A2
+    author: gary-sheng
+    chosen_by: human
+  - id: length
+    state: delegated
+    rule: as short as the claim chain allows, never over 1,200 words
+    source: design doc, Part 2
+    author: agent:claude
+    chosen_by: agent
+requirements:
+  - id: r1
+    text: a reader new to the term can say what it means after section one
+    fails_when: the simulated reader cannot define the term after section one
+    check:
+      rubric: ask the simulated reader to define the term; pass only on a correct definition
+    source: design doc, audience block
+    author: gary-sheng
+rejects:
+  - hype words about AI
+examples:
+  - path: goldens/opening.md
+    why: the claim lands in the first line and the second line earns it
+resume:
+  next_action: write the outline from the claim chain
+feedback:
+  issues: https://github.com/SupersuitUp/hyperspec/issues
+  fork: MIT; fork it for your own purposes
+improvement:
+  ledger: runs.jsonl
+---
+# Body

package/examples/runs.jsonl

@@ -0,0 +1,3 @@
+{"verdict":"one-shot"}
+{"verdict":"improved","change":"added a reject for hype words"}
+{"verdict":"not-improved","reason":"the correction was about this piece only"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@supersuit/hyperspec",
+  "version": "0.1.0",
+  "description": "A hyperspec is a spec written for an agent: every decision accounted for, every requirement failable and checked, every field traced. The standard and its linter.",
+  "type": "module",
+  "bin": {
+    "hyperspec": "bin/hyperspec.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "SPEC.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SupersuitUp/hyperspec.git"
+  },
+  "keywords": [
+    "hyperspec",
+    "specification",
+    "agents",
+    "spec-driven",
+    "outcome-factory"
+  ],
+  "dependencies": {
+    "@supersuit/superskill": "^0.2.1"
+  }
+}

package/src/load.mjs

@@ -0,0 +1,13 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parseSkillFile } from "@supersuit/superskill/yaml";
+
+export function loadSpec(path) {
+  const abs = resolve(path);
+  let text;
+  try { text = readFileSync(abs, "utf8"); } catch { return { path: abs, dir: dirname(abs), data: {}, body: "", error: `cannot read ${path}` }; }
+  const { data, body, error } = parseSkillFile(text);
+  if (error) return { path: abs, dir: dirname(abs), data: {}, body, error };
+  if (!("hyperspec" in data)) return { path: abs, dir: dirname(abs), data, body, error: "not a hyperspec" };
+  return { path: abs, dir: dirname(abs), data, body };
+}

package/src/rules.mjs

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const TESTS = Object.freeze([
+  { n: 1, name: "every decision is accounted for" },
+  { n: 2, name: "every requirement can fail" },
+  { n: 3, name: "every requirement names its check" },
+  { n: 4, name: "every field says where it came from and who wrote it" },
+  { n: 5, name: "negative space is specified" },
+  { n: 6, name: "examples outrank adjectives" },
+  { n: 7, name: "a stranger can resume it" },
+  { n: 8, name: "its adopters can push back on it" },
+  { n: 9, name: "it improves itself" },
+].map(Object.freeze));
+
+const VAGUE = /\b(engaging|compelling|high[- ]quality|good|great|clear|clean|professional|polished|nice|strong|effective|appropriate|better|amazing|excellent|best|world[- ]class|seamless|intuitive|robust)\b/i;
+// A no-action word fails only when it is the WHOLE next action: "continue drafting section two" names one.
+const NO_ACTION = /^(continue|follow[- ]?up|tbd|todo|keep going|pick (this|it) (back )?up|n\/?a|none)\W*$/i;
+// A pointer into a conversation the next reader cannot see, anywhere in the text.
+const CONVERSATION = /\bas (we )?discussed\b|\bas mentioned (earlier|above)\b/i;
+// The body scan reads prose only: fenced code blocks (``` or ~~~, closed by the same fence or the end
+// of the file) and inline code spans (a run of N backticks closed by a run of N) are removed first, so a
+// spec can quote the phrases it bans. Tables are prose and are still scanned.
+const FENCE = /^ {0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^ {0,3}\1[`~]*[ \t]*$|(?![\s\S]))/gm;
+const INLINE_CODE = /(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g;
+const prose = (body) => String(body || "").replace(FENCE, "").replace(INLINE_CODE, "");
+const list = (v) => (Array.isArray(v) ? v : []);
+// A value that is only null or ~ is a placeholder: the reader (@supersuit/superskill/yaml) keeps
+// these as the literal strings "null" and "~" rather than resolving them to YAML's own null, so
+// they must never count as present. A value that is only a YAML comment (source: # TODO) is
+// handled upstream since superskill 0.2.1: the reader returns "" for it, same as any other blank
+// scalar, so it already fails str()'s own emptiness check and needs no rule here. A QUOTED value
+// that happens to start with "#" (source: "# literal") is real text and must count as present.
+// Every presence check goes through str().
+const PLACEHOLDER = /^(null|~)$/is;
+const str = (v) => { const t = typeof v === "string" ? v.trim() : ""; return PLACEHOLDER.test(t) ? "" : t; };
+const f = (test, id, severity, message, fix) => ({ test, id, severity, message, fix });
+
+export function lintSpec(spec, { exists = existsSync } = {}) {
+  const d = spec.data || {};
+  const out = [];
+  const here = (p) => resolve(spec.dir || ".", p);
+
+  // 1 and 4, decisions
+  const decisions = list(d.decisions);
+  if (!decisions.length) out.push(f(1, "decisions", "fail", "no decisions are listed", "List every decision this kind of work has under decisions:, each decided, delegated or open."));
+  const seen = new Set();
+  decisions.forEach((x, i) => {
+    const id = str(x?.id) || `#${i + 1}`;
+    if (!str(x?.id)) out.push(f(1, "decision-id", "fail", `decision ${id} has no id`, "Give it a short id."));
+    else if (seen.has(id)) out.push(f(1, "decision-id", "fail", `decision id "${id}" is used twice`, "Make every id unique."));
+    seen.add(id);
+    const st = str(x?.state);
+    if (!["decided", "delegated", "open"].includes(st)) out.push(f(1, "decision-state", "fail", `decision "${id}" has state "${st || "(none)"}"`, "Set state to decided, delegated or open."));
+    if (st === "decided" && !str(x.value)) out.push(f(1, "decided-value", "fail", `decision "${id}" is decided with no value`, "Write the value that was decided."));
+    if (st === "delegated" && !str(x.rule)) out.push(f(1, "delegated-rule", "fail", `decision "${id}" is delegated with no rule`, "Write the rule the agent uses to decide it."));
+    if (st === "open" && !str(x.question)) out.push(f(1, "open-question", "fail", `decision "${id}" is open with no question`, "Write the question that has to be answered."));
+    if (!str(x?.source)) out.push(f(4, "decision-source", "fail", `decision "${id}" does not say where it came from`, "Add source: the brain dump line, interview answer, transcript or document."));
+    if (!str(x?.author)) out.push(f(4, "decision-author", "fail", `decision "${id}" does not say who wrote it`, "Add author: a person slug, or agent:<model>."));
+    if (!["human", "agent"].includes(str(x?.chosen_by))) out.push(f(4, "decision-chosen-by", "fail", `decision "${id}" does not say whether a human chose it`, "Add chosen_by: human or agent."));
+  });
+
+  // 2, 3 and 4, requirements
+  const reqs = list(d.requirements);
+  if (!reqs.length) out.push(f(2, "requirements", "fail", "no requirements are listed", "List what the finished work must meet under requirements:."));
+  reqs.forEach((r, i) => {
+    const id = str(r?.id) || `#${i + 1}`;
+    if (!str(r?.text)) out.push(f(2, "requirement-text", "fail", `requirement "${id}" has no text`, "Write the requirement."));
+    const fw = str(r?.fails_when);
+    if (!fw) out.push(f(2, "fails-when", "fail", `requirement "${id}" does not say what would show it failed`, "Add fails_when: something a person or a check could observe."));
+    else if (VAGUE.test(fw)) out.push(f(2, "fails-when-vague", "warn", `requirement "${id}": fails_when leans on "${fw.match(VAGUE)[0]}"`, "Replace the adjective with something observable."));
+    const c = r?.check && typeof r.check === "object" ? r.check : {};
+    if (!str(c.station) && !str(c.rubric)) out.push(f(3, "check", "fail", `requirement "${id}" names no check`, "Add check: with station: <a deterministic check> or rubric: <what a grader applies>."));
+    if (!str(r?.source)) out.push(f(4, "requirement-source", "fail", `requirement "${id}" does not say where it came from`, "Add source:."));
+    if (!str(r?.author)) out.push(f(4, "requirement-author", "fail", `requirement "${id}" does not say who wrote it`, "Add author:."));
+  });
+
+  // 5
+  // rejects items are plain strings; a non-string item is named on its own rather than hidden
+  // behind "nothing is rejected".
+  const rejects = list(d.rejects);
+  const notStrings = rejects.map((x, i) => (x != null && typeof x !== "string" ? i + 1 : 0)).filter(Boolean);
+  notStrings.forEach((n) => out.push(f(5, "rejects-item", "fail", `rejects item ${n} is not a plain string`, "Write each rejected pole as one plain line of text.")));
+  if (!notStrings.length && !rejects.some((x) => str(x))) out.push(f(5, "rejects", "fail", "nothing is rejected", "List what the work must not do under rejects:."));
+
+  // 6
+  const ex = list(d.examples);
+  if (!ex.length) out.push(f(6, "examples", "fail", "no examples are given", "Point at a real example under examples:, with path and why."));
+  ex.forEach((e, i) => {
+    const p = str(e?.path);
+    if (!p) out.push(f(6, "example-path", "fail", `example ${i + 1} has no path`, "Add path: to the example."));
+    else if (!/^https?:\/\//.test(p) && !exists(here(p))) out.push(f(6, "example-missing", "fail", `example "${p}" does not exist`, "Fix the path, or add the example file."));
+    if (!str(e?.why)) out.push(f(6, "example-why", "fail", `example ${p || i + 1} does not say why it is an example`, "Add why: what it shows that an adjective could not."));
+  });
+
+  // 7
+  const next = str(d.resume?.next_action);
+  if (!next) out.push(f(7, "next-action", "fail", "no resume.next_action", "Write the single concrete step that starts the next session."));
+  else if (NO_ACTION.test(next)) out.push(f(7, "next-action-vague", "fail", `next action "${next}" names no action`, "Name the concrete step."));
+  else if (CONVERSATION.test(next)) out.push(f(7, "next-action-vague", "fail", `next action "${next}" points into a conversation the next reader cannot see`, "State the step itself."));
+  if (CONVERSATION.test(prose(spec.body))) out.push(f(7, "conversation-pointer", "warn", "the body points into a conversation the next reader cannot see", "State the thing itself."));
+
+  // 8
+  if (!str(d.feedback?.issues)) out.push(f(8, "feedback-issues", "fail", "no feedback.issues", "Say where adopters file issues and pull requests."));
+  if (!str(d.feedback?.fork)) out.push(f(8, "feedback-fork", "fail", "no feedback.fork", "Say whether and how it may be forked."));
+
+  // 9
+  const led = str(d.improvement?.ledger);
+  if (!led) out.push(f(9, "ledger", "fail", "no improvement.ledger", "Name the file each run writes its verdict to."));
+  else {
+    // A declared ledger not yet written is fine. One that exists must be a readable file.
+    let st = null;
+    try { st = statSync(here(led)); } catch { /* not written yet */ }
+    let text = null;
+    if (st && !st.isFile()) out.push(f(9, "ledger-not-file", "fail", `ledger path ${led} is not a file`, "Point improvement.ledger at a file, one JSON object per line."));
+    else if (st) {
+      try { text = readFileSync(here(led), "utf8"); } catch (e) { out.push(f(9, "ledger-unreadable", "fail", `ledger ${led} cannot be read (${e.code || e.message})`, "Make the ledger file readable.")); }
+    }
+    (text ?? "").split("\n").filter((l) => l.trim()).forEach((line, i) => {
+      let v; try { v = JSON.parse(line); } catch { v = undefined; }
+      if (!v || typeof v !== "object" || Array.isArray(v)) { out.push(f(9, "ledger-line", "fail", `${led} line ${i + 1} is not a JSON object`, "One JSON object per line.")); return; }
+      if (!["one-shot", "improved", "not-improved"].includes(v.verdict)) out.push(f(9, "verdict", "fail", `${led} line ${i + 1}: verdict "${v.verdict}"`, "Use one-shot, improved or not-improved."));
+      if (v.verdict === "improved" && !str(v.change)) out.push(f(9, "verdict-change", "fail", `${led} line ${i + 1}: improved, but no change named`, "Say what changed."));
+      if (v.verdict === "not-improved" && !str(v.reason)) out.push(f(9, "verdict-reason", "fail", `${led} line ${i + 1}: not improved, and no reason`, "Say why nothing changed."));
+    });
+  }
+  return out;
+}

package/src/score.mjs

@@ -0,0 +1,12 @@
+import { TESTS } from "./rules.mjs";
+
+export function score(findings, data = {}) {
+  const failed = new Set(findings.filter((x) => x.severity === "fail").map((x) => x.test));
+  const tests = TESTS.map((t) => ({ n: t.n, name: t.name, pass: !failed.has(t.n) }));
+  const open = (Array.isArray(data.decisions) ? data.decisions : [])
+    .filter((x) => String(x?.state || "").trim() === "open").map((x) => String(x.id || "").trim());
+  const status = failed.size ? "fail" : open.length ? "blocked" : "pass";
+  return { tests, passed: tests.filter((t) => t.pass).length, open, status };
+}
+
+export const exitCode = (status) => ({ pass: 0, fail: 1, blocked: 3 })[status] ?? 2;

package/src/template.mjs

@@ -0,0 +1,27 @@
+export function template({ title = "Untitled", kind = "document" } = {}) {
+  return `---
+hyperspec: "0.1"
+title: ${title}
+kind: ${kind}
+decisions:
+  - id: audience
+    state: open
+    question: who reads this, and where are they on their path before they read it?
+    source: hyperspec init
+    author: agent:hyperspec-init
+    chosen_by: agent
+requirements: []
+rejects: []
+examples: []
+resume:
+  next_action: answer the open decisions, then list the requirements with fails_when and a check for each
+feedback:
+  issues: ""
+  fork: ""
+improvement:
+  ledger: runs.jsonl
+---
+
+# ${title}
+`;
+}