@supersuit/hyperspec 0.4.0 → 0.6.0

package/bin/hyperspec.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { existsSync, statSync, writeFileSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, statSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
 import { loadSpec } from "../src/load.mjs";
 import { lintSpec } from "../src/rules.mjs";
 import { score, exitCode } from "../src/score.mjs";
@@ -14,11 +14,27 @@ import { regenerate } from "../src/regenerate.mjs";
 import { compare } from "../src/compare.mjs";
 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,
@@ -43,6 +59,23 @@ const HELP = `hyperspec <command> [options]
                                with nothing in it, an --out folder that does not exist, or a --by
                                outside paragraph/sentence
 
+  dna init <scope-dir> --writer W --form F --audience A --purpose P
+                               write a new writer-DNA scope: scope.md (writer, form, audience,
+                               purpose) and an empty goldens/ folder holding a README on the
+                               golden file shape (why, approved_by, source, optional approved_on;
+                               the body is the passage, verbatim); refuses to overwrite an
+                               existing scope.md; exit 2 on a missing parent folder, a missing
+                               flag, or a flag value that looks like a placeholder (todo, ..., a
+                               bare -), never a stack trace
+  dna measure <scope-dir> [--json]
+                               read every golden in <scope-dir>/goldens/, check its required
+                               fields, and write <scope-dir>/features.json: deterministic style
+                               features measured from the goldens' text, never judged and never
+                               run through a model
+                               exit 0 wrote features.json, 1 a golden (or the scope itself) fails
+                               a required-field check, so a hollow golden is never measured into
+                               the DNA, 2 usage
+
   recipe check <output-or-recipe> [--json]
                                check a recipe's completeness (a path not ending .recipe.json
                                means <path>.recipe.json)
@@ -146,6 +179,93 @@ if (cmd === "segments") {
   process.exit(2);
 }
 
+if (cmd === "dna") {
+  const sub = argv[1];
+
+  if (sub === "init") {
+    const parsed = parseArgs(argv.slice(2), { valueFlags: ["--writer", "--form", "--audience", "--purpose"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [scopeDir] = parsed.positionals;
+    if (!scopeDir) { console.error("dna init needs a scope-dir path"); process.exit(2); }
+    for (const flagName of ["--writer", "--form", "--audience", "--purpose"]) {
+      if (!parsed.values[flagName]) { console.error(`dna init needs ${flagName} <value>`); process.exit(2); }
+    }
+    // A placeholder-looking value (todo, tbd, ..., ???, ...) is caught here rather than left
+    // for the next `dna measure` to catch on scope.md's own fields; str() is the one place that
+    // pattern is defined (src/placeholder.mjs), reused rather than re-checked.
+    for (const flagName of ["--writer", "--form", "--audience", "--purpose"]) {
+      if (!str(parsed.values[flagName])) {
+        console.error(`dna init ${flagName} "${parsed.values[flagName]}" looks like a placeholder; give it real content`);
+        process.exit(2);
+      }
+    }
+    const writer = parsed.values["--writer"];
+    const form = parsed.values["--form"];
+    const audience = parsed.values["--audience"];
+    const purpose = parsed.values["--purpose"];
+
+    const scopeAbs = resolve(scopeDir);
+    const parent = dirname(scopeAbs);
+    if (!existsSync(parent) || !statSync(parent).isDirectory()) {
+      console.error(`the folder ${dirname(scopeDir)} does not exist; create it first`);
+      process.exit(2);
+    }
+    if (existsSync(scopeAbs) && !statSync(scopeAbs).isDirectory()) {
+      console.error(`${scopeDir} is not a directory`);
+      process.exit(2);
+    }
+    // scopeMdPath (absolute, resolved from the cwd) is for filesystem operations only. Every
+    // message uses scopeMdDisplay, built from scopeDir exactly as given (relative, if that is how
+    // the operator typed it): a path the operator did not resolve themselves must never appear
+    // resolved in output, the same rule every other finding in this linter already follows.
+    const scopeMdPath = join(scopeAbs, "scope.md");
+    const scopeMdDisplay = join(scopeDir, "scope.md");
+    if (existsSync(scopeMdPath)) { console.error(`refusing to overwrite ${scopeMdDisplay}`); process.exit(2); }
+
+    mkdirSync(join(scopeAbs, "goldens"), { recursive: true });
+    writeFileSync(scopeMdPath, scopeTemplate({ writer, form, audience, purpose }));
+    // An operator's own goldens/README.md is theirs: write the guidance only where none exists.
+    try {
+      writeFileSync(join(scopeAbs, "goldens", "README.md"), GOLDENS_README, { flag: "wx" });
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+    }
+    console.log(`wrote ${scopeMdDisplay} and ${scopeDir}/goldens/. Add goldens, then run: hyperspec dna measure ${scopeDir}`);
+    process.exit(0);
+  }
+
+  if (sub === "measure") {
+    const parsed = parseArgs(argv.slice(2), { boolFlags: ["--json"] });
+    if (parsed.error) { console.error(parsed.error); process.exit(2); }
+    const [scopeDir] = parsed.positionals;
+    if (!scopeDir) { console.error("dna measure needs a scope-dir path"); process.exit(2); }
+    const json = parsed.values["--json"];
+
+    const { scope, goldens, findings } = readScope(scopeDir);
+    const hasFail = findings.some((x) => x.severity === "fail");
+    if (hasFail) {
+      if (json) console.log(JSON.stringify({ scope: scopeDir, findings }, null, 2));
+      else for (const x of findings) console.log(`fail [${x.test}] ${x.message}\n  fix: ${x.fix}`);
+      process.exit(1);
+    }
+
+    const features = measureFeatures(goldens.map((g) => g.text));
+    const { path: featuresPath } = writeFeatures(scopeDir, { scope, goldens, features });
+    if (json) {
+      console.log(JSON.stringify({ scope: scopeDir, goldens: goldens.length, features, wrote: featuresPath }, null, 2));
+    } else {
+      console.log(`${scopeDir}: measured ${goldens.length} golden${goldens.length === 1 ? "" : "s"}`);
+      console.log(`  word_count ${features.word_count}, sentence length mean ${features.sentence_length.mean} median ${features.sentence_length.median} p90 ${features.sentence_length.p90}`);
+      console.log(`  signature words: ${features.signature_words.join(", ") || "(none)"}`);
+      console.log(`wrote ${featuresPath}`);
+    }
+    process.exit(0);
+  }
+
+  console.error(`unknown dna subcommand: ${sub}\n\n${HELP}`);
+  process.exit(2);
+}
+
 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
@@ -176,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/dna/essay-new-managers-teach/features.json

@@ -0,0 +1,56 @@
+{
+  "dna": "0.1",
+  "scope": {
+    "writer": "example-author",
+    "form": "essay",
+    "audience": "new managers",
+    "purpose": "teach"
+  },
+  "goldens": [
+    {
+      "path": "goldens/close.md",
+      "sha256": "a90291714fc3bd79a16c613deb536b34c4ef577e56083c0c6b17142fbc4b871f"
+    },
+    {
+      "path": "goldens/opening.md",
+      "sha256": "395c7c37d604e255a07603276bac0d2f0915bc80d9acea45e3a30a6fe248b44e"
+    },
+    {
+      "path": "goldens/status.md",
+      "sha256": "891c34d9134380e5c752e69036ec9707729b7e30c9f2b3f2789b8d3ee3f311ed"
+    }
+  ],
+  "features": {
+    "word_count": 118,
+    "sentence_length": {
+      "mean": 13.111,
+      "median": 15,
+      "p90": 25
+    },
+    "paragraph_length": {
+      "mean_sentences": 3,
+      "mean_words": 39.333
+    },
+    "rates_per_1000_words": {
+      "comma": 33.898,
+      "semicolon": 0,
+      "colon": 8.475,
+      "em_dash": 0,
+      "en_dash": 0,
+      "exclamation": 0,
+      "question_mark": 0,
+      "parentheses": 0,
+      "quotation_marks": 0
+    },
+    "contraction_rate": 0,
+    "first_person_singular_rate": 0,
+    "first_person_plural_rate": 0,
+    "second_person_rate": 59.322,
+    "mean_word_length": 3.831,
+    "signature_words": [
+      "first",
+      "report",
+      "tracker"
+    ]
+  }
+}

package/examples/writing/dna/essay-new-managers-teach/goldens/README.md

@@ -0,0 +1,14 @@
+# Goldens
+
+Each file in this folder except this one is a golden: a passage the writer marked as right,
+filed under this scope.
+
+Frontmatter:
+- why (required): what makes it golden, the move it teaches.
+- approved_by (required): a person slug. Golden means a human approved it; agent:* is refused.
+- source (required): where the passage came from.
+- approved_on (optional): a date.
+
+The body is the passage, verbatim.
+
+Run `hyperspec dna measure <scope-dir>` once every golden here has why, approved_by and source.

package/examples/writing/dna/essay-new-managers-teach/goldens/close.md

@@ -0,0 +1,9 @@
+---
+why: ends on an instruction and gives the reason for it in the same sentence
+approved_by: example-author
+source: first draft of this essay's closing paragraph, marked golden on the review page
+approved_on: "2026-09-18"
+---
+
+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.

package/examples/writing/dna/essay-new-managers-teach/goldens/opening.md

@@ -0,0 +1,9 @@
+---
+why: one plain claim in the first sentence, then two short sentences that turn it into something to do
+approved_by: example-author
+source: first draft of this essay's opening paragraph, marked golden on the review page
+approved_on: "2026-09-18"
+---
+
+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.

package/examples/writing/dna/essay-new-managers-teach/goldens/status.md

@@ -0,0 +1,10 @@
+---
+why: states what to stop doing, then where that thing already lives, then what the freed half hour is for, one sentence each
+approved_by: example-author
+source: an earlier newsletter essay for new managers by the same writer, its middle section
+approved_on: "2026-09-18"
+---
+
+If you can read it in the tracker, do not ask for it in the room. Status already has a home,
+and your report is the one who put it there. Spend the half hour on what the tracker cannot
+hold: how the work looks from their side of it.

package/examples/writing/dna/essay-new-managers-teach/scope.md

@@ -0,0 +1,11 @@
+---
+writer: example-author
+form: essay
+audience: new managers
+purpose: teach
+---
+
+# Writer DNA scope
+
+Goldens live in goldens/. Run `hyperspec dna measure <scope-dir>` once every golden there has
+why, approved_by and source.

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.

package/examples/writing/essay/materials/interview-notes.md.segments.jsonl

@@ -3,8 +3,8 @@
 {"id":"s2","start":119,"end":199,"label":"aside","text":"Considered: the manager reviewed these notes afterwards and corrected two\nlines."}
 {"id":"s3","start":201,"end":240,"label":"claim","source":"interview with an engineering manager of eight years","text":"- Her rule: the report owns the agenda."}
 {"id":"s4","start":241,"end":356,"label":"claim","source":"interview with an engineering manager of eight years","text":"She keeps a shared document per person; they add items\n  before the meeting, and she adds hers last, at the bottom."}
-{"id":"s5","start":357,"end":448,"label":"quote","speaker":"the engineering manager interviewed","text":"- \"If I have something urgent, it is not a one-on-one topic. I send it the day it happens.\""}
+{"id":"s5","start":357,"end":448,"label":"quote","speaker":"dana, an engineering manager","text":"- \"If I have something urgent, it is not a one-on-one topic. I send it the day it happens.\""}
 {"id":"s6","start":449,"end":617,"label":"claim","source":"interview with an engineering manager of eight years","text":"- The first one-on-one with a new report is always the same: she asks how they like to receive\n  feedback, in writing or out loud, right away or at the end of the week."}
 {"id":"s7","start":618,"end":673,"label":"claim","source":"interview with an engineering manager of eight years","text":"- Her warning: new managers treat silence as a problem."}
-{"id":"s8","start":674,"end":733,"label":"quote","speaker":"the engineering manager interviewed","text":"\"Wait. Count to five. The real answer is\n  the second one.\""}
+{"id":"s8","start":674,"end":733,"label":"quote","speaker":"dana, an engineering manager","text":"\"Wait. Count to five. The real answer is\n  the second one.\""}
 {"id":"s9","start":734,"end":812,"label":"claim","source":"interview with an engineering manager of eight years","text":"- She cancels a one-on-one only when the report asks her to, never on her own."}

package/examples/writing/essay.hyperspec.md

@@ -28,7 +28,7 @@ requirements:
     fails_when: a reader shown only the first two sentences cannot say who should set the agenda
     check:
       rubric: show the simulated reader the first two sentences and ask who sets the agenda; pass only on "the report"
-    source: essay/goldens/opening.md
+    source: dna/essay-new-managers-teach/goldens/opening.md
     author: example-author
   - id: r2
     text: the three questions appear word for word as the voice memo states them
@@ -71,10 +71,10 @@ rejects:
   - any claim about what most managers do that the survey does not support
   - the walking one-on-one aside from the voice memo
 examples:
-  - path: essay/goldens/opening.md
-    why: the claim lands in the first sentence, and the second sentence turns it into an instruction
+  - path: dna/essay-new-managers-teach/goldens/opening.md
+    why: the claim lands in the first sentence, and the two short sentences after it turn it into an instruction
 resume:
-  next_action: outline the four spine claims against the form's required parts, citing the segments each claim points at
+  next_action: hand essay/draft.md to the doctor for the rubric checks in r1, r4 and r5, now that hyperspec check passes it
 feedback:
   issues: https://github.com/SupersuitUp/hyperspec/issues
   fork: MIT; fork it for your own purposes
@@ -110,18 +110,21 @@ writing:
     author: agent:claude
   dna:
     writer: example-author
+    scope_dir: dna/essay-new-managers-teach
     scope:
       form: essay
       audience: new managers
       purpose: teach
     rules: style-rules.md
     goldens:
-      - path: essay/goldens/opening.md
-        why: one plain claim, then a second sentence that turns it into something to do
-      - path: essay/goldens/close.md
+      - path: dna/essay-new-managers-teach/goldens/opening.md
+        why: one plain claim in the first sentence, then two short sentences that turn it into something to do
+      - path: dna/essay-new-managers-teach/goldens/status.md
+        why: states what to stop doing, then where that thing already lives, then what the freed half hour is for, one sentence each
+      - path: dna/essay-new-managers-teach/goldens/close.md
         why: ends on an instruction and gives the reason for it in the same sentence
     check:
-      rubric: blind lineup within this scope; a judge shown the generated opening beside the two goldens cannot pick it out
+      rubric: blind lineup within this scope; a judge shown a generated passage beside the scope's three goldens cannot pick it out
     source: goldens marked on the review page
     author: example-author
   persona:
@@ -145,6 +148,9 @@ writing:
       - one-on-one
       - report
       - tracker
+    terms:
+      - running agenda
+      - status meeting
     believes_now: a one-on-one is where a manager catches up on how the work is going
     wants: a plan for the first meeting that will not waste either person's half hour
     reads_on: a phone, in the ten minutes before the meeting
@@ -173,11 +179,11 @@ writing:
       max: 1100
       unit: words
     required_parts:
-      - an opening that states the claim
-      - the story of the author's first one-on-one
+      - who sets the agenda
+      - my first one-on-one
       - the three questions
       - what to do with the answers
-      - a close the reader can act on
+      - before the meeting
     stations:
       - the three questions render as a numbered list
     check:
@@ -216,5 +222,18 @@ fiction: false
 # Hand your first one-on-one to the person you manage
 
 A worked example of the writing profile: an essay for new managers, specified before a word of
-it is drafted. Every file this spec names ships beside it. `essay/claims.jsonl` does not exist
-yet, because the claims ledger is written during drafting.
+it is drafted. Every file this spec names ships beside it. The draft is `essay/draft.md`, and
+the claims ledger written while drafting it is `essay/claims.jsonl`. The draft passes every
+deterministic station:
+
+```bash
+npx @supersuit/hyperspec check essay.hyperspec.md --draft essay/draft.md
+```
+
+The required parts are the draft's section headings, because the form station finds a required
+part by its heading.
+
+The writer's voice for this piece comes from a scope folder, `dna/essay-new-managers-teach/`:
+the goldens this writer approved for essays that teach new managers, and the features measured
+from them. Another essay by the same writer, for the same readers and the same purpose, would
+point at the same folder.

package/examples/writing/story/claims.jsonl

@@ -0,0 +1,9 @@
+{"text":"Flour is weighed at Ines's, never scooped.","source":"bakery-visit#s10","span":"Flour is weighed, never scooped."}
+{"text":"The water temperature is checked every batch at Ines's","source":"bakery-visit#s11","span":"Water temperature is checked every batch."}
+{"text":"Ines does not talk while she shapes.","source":"bakery-visit#s8","span":"The owner does not talk while shaping."}
+{"text":"Talking happens at the mixer and at the till","source":"bakery-visit#s9","span":"Talking happens at the mixer and at the till."}
+{"text":"In winter the rye proofs about three hours at room temperature.","source":"bakery-visit#s4","span":"Rye sourdough proofs about three hours at room temperature in winter."}
+{"text":"The back left of the deck oven runs hot, so every tray is turned halfway through the bake.","source":"bakery-visit#s5","span":"Trays are turned halfway through the bake because the back left of a deck oven runs hot."}
+{"text":"The doors open to customers at 7:00.","source":"bakery-visit#s6","span":"The doors open to customers at 7:00."}
+{"text":"The first person in is usually a regular.","source":"bakery-visit#s7","span":"The first person in is usually a regular."}
+{"text":"turning those trays with her since I was sixteen","source":"notes#s2","span":"the apprentice she took on at sixteen, now nineteen"}