@supersuit/hyperspec 0.4.0 → 0.6.0

package/src/stations/quotes.mjs

@@ -0,0 +1,168 @@
+// Station "quotes" (hyperspec 0.6). Every double-quoted span in the draft of 4 or
+// more words must appear in a `quote` or `story` segment of a marked material; a quote the draft
+// attributes to someone by name must appear in a `quote` segment whose speaker is that someone.
+// Pure and deterministic: no model call, no judgment about what counts as quoting, just the closed
+// rules below.
+//
+// What counts as a quoted span: text between a pair of straight double quotes ("...") or a pair of
+// curly ones (U+201C ... U+201D), paired left to right WITHIN one paragraph, so a stray quote mark
+// can never pair with one in a later paragraph and swallow everything between. Fenced code and
+// inline code are masked first (util.mjs's maskCode): a quote inside example syntax is not the
+// writer quoting anyone. A span is checked only when it holds 4 or more words (dna.mjs's wordsOf,
+// the one word definition every station shares); shorter spans are scare quotes and titles as
+// often as they are quotations.
+//
+// Matching: both sides are normalized the same way (curly quotes and apostrophes to straight,
+// whitespace runs to one space, ends trimmed; case is kept, so a changed capital is a changed
+// quote). The span also drops trailing commas and periods before matching, because typographic
+// convention puts a sentence's own comma or period inside the closing quote ("...at a time," he
+// said) whether or not the speaker's sentence ended there. The normalized span must then appear as
+// a substring of some quote or story segment's text, in any marked material of the spec.
+//
+// Attribution: a speaker is any `speaker` value on a quote segment. It is named in the draft
+// when the sentence that holds the quote contains, case-insensitively and as whole
+// words, EITHER the full value (split on anything that is not a letter, digit or apostrophe, so the
+// slug "maria-lopez" reads as "maria lopez", its words joined in the draft by whitespace, hyphens or
+// underscores) OR the value's first word alone ("Maria said" names maria-lopez; "Mariana" does not).
+// The first word alone counts only when it has 2 or more letters and is not one of dna.mjs's
+// STOPWORDS: a speaker recorded as "the manager interviewed" would otherwise be named by every
+// sentence holding "the". Such a speaker is still named by its full value. The sentence is read
+// with the quote itself blanked out (a name inside the quoted words is what was said, not who said it). A named speaker
+// means the span must be in a quote segment with that speaker; matching only some other speaker's
+// quote, or only a story, is `station-quotes-misattributed`. With no speaker named, any quote or
+// story segment is enough. Sentences come from splitSegments(text, { by: "sentence" }), and every
+// sentence the span overlaps is read, so a curly quote the splitter cuts in two still keeps its
+// attribution.
+
+import { splitSegments } from "../segments.mjs";
+import { STOPWORDS, wordsOf } from "../dna.mjs";
+import { str } from "../placeholder.mjs";
+import { lineAt, maskCode, markedSegments, truncate } from "./util.mjs";
+
+export const name = "quotes";
+
+const QUOTE_RE = /"([^"]*)"|“([^“”]*)”/g;
+const WORD_CLASS = "\\p{L}\\p{N}'’";
+
+function normalize(text) {
+  return String(text)
+    .replace(/[‘’‚‛]/g, "'")
+    .replace(/[“”„‟]/g, '"')
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// What a quoted span is matched on: normalized, then trailing commas and periods dropped.
+// Typographic convention puts the writer's own comma or period inside the closing quote
+// ("...at a time," he said) whether or not the speaker's sentence ended there, so keeping them
+// would fail nearly every quotation used mid-sentence. "?" and "!" are kept: adding either changes
+// what was said.
+const matchKey = (inner) => normalize(inner).replace(/[.,]+$/, "").trim();
+
+// Every quoted span in `text`, as { start, end, inner }: start/end bound the whole span including
+// its quote marks, inner is the text between them. Paired per paragraph (see the header).
+function quotedSpans(text) {
+  const spans = [];
+  for (const para of splitSegments(text, { by: "paragraph" })) {
+    QUOTE_RE.lastIndex = 0;
+    let m;
+    while ((m = QUOTE_RE.exec(para.text))) {
+      spans.push({ start: para.start + m.index, end: para.start + m.index + m[0].length, inner: m[1] ?? m[2] ?? "" });
+    }
+  }
+  return spans;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+const STOPWORD_SET = new Set(STOPWORDS);
+
+// Whether a speaker's first word may name the speaker on its own: 2 or more letters, and not a
+// stopword (compared lowercased, apostrophes as written).
+function firstWordNames(word) {
+  const letters = word.match(/\p{L}/gu)?.length ?? 0;
+  return letters >= 2 && !STOPWORD_SET.has(word.toLowerCase());
+}
+
+// A speaker value as a whole-word, case-insensitive pattern matching its full words, or its first
+// word alone when firstWordNames allows it; null when it has no words at all.
+export function speakerPattern(value) {
+  const words = value.split(new RegExp(`[^${WORD_CLASS}]+`, "u")).filter(Boolean);
+  if (!words.length) return null;
+  const full = words.map(escapeRe).join("[\\s_-]+");
+  const alts = firstWordNames(words[0]) && words.length > 1 ? `${full}|${escapeRe(words[0])}` : full;
+  return new RegExp(`(?<![${WORD_CLASS}])(?:${alts})(?![${WORD_CLASS}])`, "iu");
+}
+
+// The text of every sentence the span overlaps, with the span itself blanked out.
+function attributionContext(text, sentences, span) {
+  const over = sentences.filter((s) => s.start < span.end && s.end > span.start);
+  const from = over.length ? Math.min(span.start, over[0].start) : span.start;
+  const to = over.length ? Math.max(span.end, over[over.length - 1].end) : span.end;
+  return `${text.slice(from, span.start)} ${text.slice(span.end, to)}`;
+}
+
+export function run(spec, draft, ctx) {
+  // Fiction: a character's line is invented, not quoted from a material, so holding dialogue to
+  // the marked quotes would fail every story that uses quotation marks. The character stations of a
+  // later release check dialogue against each character's golden and rejected lines instead.
+  if (str(spec?.data?.fiction) === "true") {
+    return { station: name, status: "skip", findings: [], reason: "fiction dialogue is checked by the character stations in a later release" };
+  }
+  const text = maskCode(draft.text);
+  const spans = quotedSpans(text).filter((s) => wordsOf(s.inner).length >= 4);
+  if (!spans.length) return { station: name, status: "pass", findings: [] };
+
+  // Every quote and story segment across every marked material, normalized once. A speaker's key
+  // is its value lowercased; shownSpeaker keeps the first spelling the material wrote, for findings.
+  const sources = [];
+  const shownSpeaker = new Map();
+  for (const { segments } of markedSegments(spec, ctx)) {
+    for (const seg of segments) {
+      if ((seg.label !== "quote" && seg.label !== "story") || typeof seg.text !== "string") continue;
+      const speaker = seg.label === "quote" && typeof seg.speaker === "string" ? seg.speaker.trim() : "";
+      const key = speaker.toLowerCase();
+      if (key && !shownSpeaker.has(key)) shownSpeaker.set(key, speaker);
+      sources.push({ label: seg.label, speaker: key, norm: normalize(seg.text) });
+    }
+  }
+  const speakers = [...shownSpeaker.keys()]
+    .map((key) => ({ key, re: speakerPattern(key) }))
+    .filter((sp) => sp.re);
+
+  const sentences = splitSegments(text, { by: "sentence" });
+  const findings = [];
+  for (const span of spans) {
+    const key = matchKey(span.inner);
+    if (!key) continue;
+    const shown = truncate(span.inner.replace(/\s+/g, " "), 80);
+    const line = lineAt(draft.text, span.start);
+    const hits = sources.filter((s) => s.norm.includes(key));
+    if (!hits.length) {
+      findings.push({
+        station: name,
+        id: "station-quotes-unmatched",
+        severity: "fail",
+        line,
+        message: `quoted span "${shown}" does not appear in any quote or story segment of a marked material`,
+        fix: "Quote the material verbatim, or drop the quotation marks and paraphrase.",
+      });
+      continue;
+    }
+    const around = attributionContext(text, sentences, span);
+    const named = speakers.filter((sp) => sp.re.test(around)).map((sp) => sp.key);
+    if (named.length && !hits.some((h) => h.label === "quote" && named.includes(h.speaker))) {
+      const who = named.map((k) => shownSpeaker.get(k) ?? k).join(", ");
+      findings.push({
+        station: name,
+        id: "station-quotes-misattributed",
+        severity: "fail",
+        line,
+        message: `quoted span "${shown}" is attributed to ${who} in its sentence, but no quote segment by ${who} contains it`,
+        fix: `Attribute the quote to whoever the material records saying it, or quote what ${who} actually said.`,
+      });
+    }
+  }
+
+  return { station: name, status: findings.length ? "fail" : "pass", findings };
+}

package/src/stations/terms.mjs

@@ -0,0 +1,131 @@
+// Station "terms" (hyperspec 0.6). Checks that every term in
+// writing.audience.terms (the new optional list: terms the piece uses that the reader may not
+// know) is defined the first time it appears in the draft. Pure and deterministic like every
+// station: no model call, no judgment about which words are jargon, just the closed rule below.
+//
+// Matching a term against the draft is case-insensitive and whole-word (Unicode-aware: a match
+// cannot start or end mid-word, using the same letter/number/apostrophe class dna.mjs's own word
+// definition uses, so "AI" does not match inside "said" and a multi-word term like "context
+// window" matches only as that exact phrase).
+//
+// "Defined at its first appearance" is read as: the sentence containing
+// the term's first appearance, OR the sentence right after it, contains an occurrence of the term
+// followed (within the next 6 words of that same sentence, or by a colon among them) by one of
+// "is", "means", "refers to"; OR the term is immediately followed by a parenthetical ("term
+// (short gloss)"). Sentence boundaries come from splitSegments(text, { by: "sentence" }) in
+// src/segments.mjs, the same splitter every other station that reads sentences uses, so "which
+// sentence is this in" never disagrees between stations.
+//
+// A term also listed in writing.audience.knows is never flagged, whatever the draft does with it:
+// the reader is assumed to already have it. A term that never appears in the draft at all is not
+// flagged either (nothing to define); writing.audience.terms with no real entries, or missing
+// entirely, skips the whole station.
+//
+// Fenced code blocks and inline code spans are masked out (src/stations/util.mjs's maskCode)
+// before any of the above runs: a term's only appearance inside example syntax like
+// `` `ledger: check` `` is not a prose use, and the mechanical colon/`is` rule below would
+// otherwise read that code span's own punctuation as a definition it never gave. Masking
+// preserves every character offset, so every 1-based line number reported below is still a line
+// of the ORIGINAL draft, never the masked copy.
+
+import { str } from "../placeholder.mjs";
+import { splitSegments } from "../segments.mjs";
+import { lineAt, maskCode } from "./util.mjs";
+
+export const name = "terms";
+
+// The same word/number class dna.mjs's WORD_RE tokenizes with (letters, digits, straight or
+// curly apostrophe for contractions), Unicode-aware so an accented or non-Latin term's edges are
+// read correctly too.
+const WORD_CHARS = "\\p{L}\\p{N}'’";
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// A case-insensitive, whole-phrase, Unicode-aware matcher for `term`: it cannot start or end
+// mid-word (a lookbehind/lookahead against the word-char class above), but the term itself may
+// contain internal spaces (a multi-word term matches only as that exact phrase, spaces and all).
+function termRegex(term, flags) {
+  const body = escapeRegExp(term.trim()).replace(/\s+/g, "\\s+");
+  return new RegExp(`(?<![${WORD_CHARS}])${body}(?![${WORD_CHARS}])`, flags);
+}
+
+// Every { word, start, end } token in `text`, in order, using the same word-char class as above.
+function tokenize(text) {
+  const re = new RegExp(`[${WORD_CHARS}]+`, "gu");
+  const out = [];
+  let m;
+  while ((m = re.exec(text))) out.push({ word: m[0].toLowerCase(), start: m.index, end: m.index + m[0].length });
+  return out;
+}
+
+// Whether `sentenceText` contains a definition of `term`: some occurrence of the term followed,
+// within the next 6 words of the SAME sentence (or by a colon somewhere among them), by "is",
+// "means" or "refers"+"to"; or immediately (skipping only whitespace) followed by "(".
+function definesTerm(sentenceText, term) {
+  const re = termRegex(term, "giu");
+  let m;
+  while ((m = re.exec(sentenceText))) {
+    const tailStart = m.index + m[0].length;
+    const tail = sentenceText.slice(tailStart);
+    if (/^\s*\(/.test(tail)) return true;
+
+    const tokens = tokenize(tail).slice(0, 6);
+    const windowEnd = tokens.length ? tokens[tokens.length - 1].end : tail.length;
+    const window = tail.slice(0, windowEnd);
+    if (window.includes(":")) return true;
+    const words = tokens.map((t) => t.word);
+    if (words.includes("is") || words.includes("means")) return true;
+    if (words.some((w, i) => w === "refers" && words[i + 1] === "to")) return true;
+    // re is not global-sticky across iterations by construction (lastIndex advances past this
+    // match automatically since the "g" flag is set), so a term repeated in one sentence is
+    // still checked occurrence by occurrence rather than looping forever.
+  }
+  return false;
+}
+
+export function run(spec, draft) {
+  const audience = spec?.data?.writing?.audience ?? {};
+  const terms = Array.isArray(audience.terms) ? audience.terms.map(str).filter(Boolean) : [];
+  if (!terms.length) {
+    return { station: name, status: "skip", findings: [], reason: "writing.audience.terms is empty or not set" };
+  }
+
+  const knows = new Set((Array.isArray(audience.knows) ? audience.knows : []).map((x) => str(x).toLowerCase()).filter(Boolean));
+
+  const scanText = maskCode(draft.text);
+  const sentences = splitSegments(scanText, { by: "sentence" });
+  const findings = [];
+  const usedIds = new Set();
+
+  for (const term of terms) {
+    if (knows.has(term.toLowerCase())) continue;
+
+    const first = termRegex(term, "iu").exec(scanText);
+    if (!first) continue; // the term never appears outside code; nothing to define
+
+    const pos = first.index;
+    const idx = sentences.findIndex((s) => pos >= s.start && pos < s.end);
+    const candidates = idx === -1 ? [] : [sentences[idx], sentences[idx + 1]].filter(Boolean);
+    const defined = candidates.some((s) => definesTerm(s.text, term));
+    if (defined) continue;
+
+    const slug = term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "term";
+    let id = `station-terms-undefined-${slug}`;
+    let n = 2;
+    while (usedIds.has(id)) { id = `station-terms-undefined-${slug}-${n}`; n += 1; }
+    usedIds.add(id);
+
+    findings.push({
+      station: name,
+      id,
+      severity: "fail",
+      line: lineAt(draft.text, pos),
+      message: `term "${term}" is not defined at its first appearance (need "is", "means", "refers to", a colon within a few words, or an immediate parenthetical, in that sentence or the next)`,
+      fix: `Define "${term}" where it first appears, e.g. "${term} is ..." or "${term} (a short gloss)".`,
+    });
+  }
+
+  return { station: name, status: findings.length ? "fail" : "pass", findings };
+}

package/src/stations/util.mjs

@@ -0,0 +1,99 @@
+import { resolve } from "node:path";
+import { str } from "../placeholder.mjs";
+import { readSegments } from "../segments.mjs";
+
+// Shared helpers for the deterministic stations (hyperspec 0.6). "One place this pattern is
+// defined" (src/placeholder.mjs's own header comment), so a helper more than one station needs
+// lives here rather than being copied station to station: lineAt, truncate, maskCode, maskRanges
+// and markedSegments.
+
+// The 1-based line containing character offset `pos` of `text`. Counts "\n" characters directly
+// rather than reading draft.lines: draft.lines' own CRLF handling ("\r" left attached to the
+// previous line's entry, or stripped, depending on how src/check.mjs built it) is none of any
+// station's business, and counting "\n" occurrences gives the right line number either way, since
+// every line, CRLF or not, still carries exactly one "\n".
+export function lineAt(text, pos) {
+  let line = 1;
+  for (let i = 0; i < pos && i < text.length; i++) if (text[i] === "\n") line++;
+  return line;
+}
+
+// Trims `text`, then truncates to at most `max` characters (an ellipsis replacing the last
+// character when it is longer), matching the general finding-message rule that a quoted span of
+// the draft is at most 80 characters. Trimming FIRST means a span with leading/trailing
+// whitespace never wastes truncation budget on it.
+export function truncate(text, max) {
+  const t = String(text).trim();
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+// `text` with every [start, end) range in `ranges` blanked out: every character in the range
+// becomes a space, EXCEPT "\n", which is left alone. Preserving newlines (rather than blanking
+// them too) is what keeps every character offset, and therefore every 1-based line number
+// computed afterward, identical to `text` before masking, even when a masked range spans more
+// than one line (a fenced code block, in particular): blanking a "\n" would merge two lines into
+// one for every offset that comes after it, which is exactly the bug a single-line-only masker
+// would not have caught. Used by every "mask X out before scanning for Y" step across the
+// stations, so a masked-and-rescanned span can never be matched a second time.
+export function maskRanges(text, ranges) {
+  let out = text;
+  for (const { start, end } of ranges) {
+    const blanked = out.slice(start, end).replace(/[^\n]/g, " ");
+    out = out.slice(0, start) + blanked + out.slice(end);
+  }
+  return out;
+}
+
+// A fenced code block: a line starting (after up to 3 spaces of indent) with 3 or more backticks
+// or tildes, some content, then a line starting with at least as many of the SAME fence
+// character. Non-greedy so back-to-back fences in one draft are matched as separate blocks
+// rather than one block swallowing everything between the first open and the last close.
+const FENCE_RE = /^[ \t]{0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?^[ \t]{0,3}\1[ \t]*$/gm;
+
+// An inline code span: a single backtick, a run of non-backtick, non-newline characters, a
+// closing backtick. Does not attempt CommonMark's full rule for spans opened with a run of two or
+// more backticks (rare in practice, and unneeded for the case this exists to fix: an inline
+// `like this` mention of syntax that must not be read as prose).
+const INLINE_CODE_RE = /`[^`\n]+`/g;
+
+// `text` with every fenced code block and inline code span blanked out (offsets and line numbers
+// preserved, see maskRanges above). Both `links` (a URL shown as example syntax inside a fence or
+// a span is not a real, followable link) and `terms` (a term's only appearance inside `` `code`
+// `` is not a prose use, and must not count toward "does this term appear/get defined") mask code
+// out before doing anything else, so later masking passes (Markdown links, reference definitions,
+// bare URLs, sentence splitting) never see inside a code span or fence.
+export function maskCode(text) {
+  const fenceRanges = [];
+  FENCE_RE.lastIndex = 0;
+  let m;
+  while ((m = FENCE_RE.exec(text))) fenceRanges.push({ start: m.index, end: m.index + m[0].length });
+  const withoutFences = maskRanges(text, fenceRanges);
+
+  const inlineRanges = [];
+  INLINE_CODE_RE.lastIndex = 0;
+  let im;
+  while ((im = INLINE_CODE_RE.exec(withoutFences))) inlineRanges.push({ start: im.index, end: im.index + im[0].length });
+  return maskRanges(withoutFences, inlineRanges);
+}
+
+// Every marked material of the spec, as [{ material, segments }], in writing.materials.items
+// order: an item with a segments: field whose file readSegments can read. The segments file
+// resolves relative to spec.dir, the way every writing path does. readSegments' own findings are
+// dropped here on purpose: lint reports them (test 1 and 4) and check only runs once lint passes,
+// so a station reading materials only needs the segments themselves. quotes and private both
+// read this, so it is cached on ctx (one read per check run, whichever station asks first); a
+// caller that passes no ctx simply reads the files again.
+export function markedSegments(spec, ctx) {
+  if (ctx && ctx.markedSegments) return ctx.markedSegments;
+  const items = spec?.data?.writing?.materials?.items;
+  const out = [];
+  for (const item of Array.isArray(items) ? items : []) {
+    const segPath = str(item?.segments);
+    if (!segPath) continue;
+    const material = str(item?.id) || segPath;
+    const { segments } = readSegments(resolve(spec?.dir || ".", segPath), { materialId: str(item?.id) || undefined });
+    out.push({ material, segments: segments.filter((s) => s && typeof s === "object") });
+  }
+  if (ctx) ctx.markedSegments = out;
+  return out;
+}

package/src/writing-exports.mjs

@@ -1,6 +1,11 @@
-// @supersuit/hyperspec/writing: the reading side of materials marking, for a tool outside this
-// package that labels materials (an agent, an editor, the writing engine's capture stage). It gets
+// @supersuit/hyperspec/writing: the reading side of the writing profile, for a tool outside this
+// package. For materials marking (an agent, an editor, the writing engine's capture stage) it gets
 // the closed label set and the same parse-and-validate the linter runs; labeling itself stays with
-// whoever calls this.
+// whoever calls this. For scoped writer DNA it gets readScope, the same read of a scope folder
+// (scope.md plus every golden, with their field findings) that `hyperspec lint` and
+// `hyperspec dna measure` run, and measureFeatures, the pure function that turns golden passages
+// into the numbers features.json records. Judging a draft against those numbers stays with the
+// caller.
 export { MATERIAL_LABELS } from "./labels.mjs";
 export { readSegments } from "./segments.mjs";
+export { readScope, measureFeatures } from "./dna.mjs";

package/src/writing-fields.mjs

@@ -18,9 +18,11 @@
 // (test 1), because dialogue cannot be specified without them. relationships stays optional: a
 // character may genuinely relate to no one yet, and nothing gives it a closed set or a count.
 
-import { statSync } from "node:fs";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
 import { str } from "./placeholder.mjs";
 import { readSegments } from "./segments.mjs";
+import { readScope, isGoldenFileName, measureFeatures, featuresText, DNA_FORMAT } from "./dna.mjs";
 
 const f = (test, id, severity, message, fix) => ({ test, id, severity, message, fix });
 const list = (v) => (Array.isArray(v) ? v : []);
@@ -131,16 +133,151 @@ const UNRESOLVABLE_BECAUSE = {
 
 // ---------------------------------------------------------------- 2. dna ----------------------
 
+// writing.dna.scope_dir (0.5, optional): the path (relative to the spec, like every other path in
+// this file) to a scoped-DNA folder built by `hyperspec dna init`/`dna measure` (src/dna.mjs).
+// The KEY being absent means none of the checks below run: 0.4 behavior, unchanged. A key that IS
+// present but placeholder-ish (TODO, tbd, an empty string) fails on its own (test 1,
+// writing-dna-scope-dir, naming the value) before any of this runs, since a real value is what
+// every check below needs. Present with a real value, four things must all hold:
+// - scope.md's writer/form/audience/purpose agree with dna.writer/dna.scope (test 1);
+// - every dna.goldens[].path is one of the goldens readScope actually reads: resolved through
+//   any symlink, a golden-named file directly in the scope's REAL goldens/ folder (test 5,
+//   writing-dna-golden-leak, naming the golden and the scope). Anything else feeds the spec a
+//   passage that is never checked or measured under this scope. A goldens/ folder that itself
+//   resolves outside the scope is readScope's own finding (writing-dna-goldens-outside), which
+//   stands in for the per-golden findings it would otherwise cause;
+// - every golden IN the scope passes its own field checks, exactly readScope's findings, reused
+//   rather than re-derived, with displayDir set to the scope_dir string the spec wrote (never a
+//   resolved filesystem path, so a finding here never names this machine's folders);
+// - <scope_dir>/features.json is current: byte for byte what `dna measure` would write now
+//   (test 6), with the stale finding naming what differs.
+function isInsideDir(parentAbs, childAbs) {
+  return childAbs === parentAbs || childAbs.startsWith(parentAbs + sep);
+}
+
+const realOrNull = (p) => { try { return realpathSync(p); } catch { return null; } };
+
+// Why a listed golden is not one of the scope's goldens, as the words of the leak finding, or
+// null when it is one. lexicalGoldens is <scope_dir>/goldens as written; realGoldens is where
+// that folder really is.
+function leakReason(lexicalGoldens, realGoldens, goldenAbs) {
+  const real = realOrNull(goldenAbs);
+  if (real && realGoldens && dirname(real) === realGoldens && isGoldenFileName(basename(real))) return null;
+  if (!isInsideDir(lexicalGoldens, goldenAbs)) return "outside";
+  if (!real || !realGoldens || !isInsideDir(realGoldens, real)) return "symlink";
+  return "not-a-golden";
+}
+
+function leakFinding(idPrefix, reason, p, i, scopeDirRaw) {
+  const where = `${scopeDirRaw}/goldens/`;
+  if (reason === "outside") {
+    return f(5, `${idPrefix}-golden-leak`, "fail",
+      `golden "${p}" feeds only work that shares its scope; it does not live under ${where}`,
+      `Move ${p} into ${where}, or point dna.goldens[${i + 1}].path at a golden already there.`);
+  }
+  if (reason === "symlink") {
+    return f(5, `${idPrefix}-golden-leak`, "fail",
+      `golden "${p}" is a symlink that resolves outside ${where} (or sits in a folder that does), so it feeds this scope a passage from somewhere else`,
+      `Replace the link at ${p} with the passage itself, as a file in ${where} with why, approved_by and source.`);
+  }
+  return f(5, `${idPrefix}-golden-leak`, "fail",
+    `golden "${p}" is not one of the scope's goldens: only .md files directly in ${where}, other than README.md, are read, checked and measured`,
+    `Put the passage in its own .md file directly in ${where}, with why, approved_by and source, and point dna.goldens[${i + 1}].path at it.`);
+}
+
+// One field of the spec's own dna claim against the same field read off scope.md. Silent when
+// either side is empty: an empty spec-side value already fails its own presence check above (e.g.
+// writing-dna-writer), and an empty disk-side value already fails as one of readScope's own
+// findings (e.g. writing-dna-scope-file-writer); comparing two things when one is already known-broken
+// would just be a second name for the same defect, not a second defect.
+function scopeMismatch(out, idPrefix, scopeDirRaw, label, idSuffix, specVal, diskVal) {
+  const a = str(specVal);
+  const b = str(diskVal);
+  if (!a || !b || a.trim().toLowerCase() === b.trim().toLowerCase()) return;
+  out.push(f(1, `${idPrefix}-scope-mismatch-${idSuffix}`, "fail",
+    `writing.dna.scope_dir "${scopeDirRaw}": ${label} "${a}" does not match ${scopeDirRaw}/scope.md's ${label} "${b}"`,
+    `Make writing.dna's ${label} and ${scopeDirRaw}/scope.md's ${label} agree; one of them is wrong.`));
+}
+
+// Whether <scope>/features.json is what `dna measure` would write now. Returns "missing" (absent
+// or not JSON), null (current), or the words naming what differs: goldens added, removed or
+// changed by hash; scope fields that differ from scope.md; a dna format this linter does not
+// know; features that differ from a fresh measurement (only named when the goldens themselves
+// are unchanged, since changed goldens explain every number); and, when nothing more specific
+// differs, bytes dna measure would not have written. Exported so the check command's dna station
+// (src/stations/dna.mjs) skips on exactly the staleness lint fails a spec for, never a second
+// definition of it.
+export function featuresStaleness(featuresPath, diskScope, diskGoldens) {
+  let text;
+  let recorded;
+  try {
+    text = readFileSync(featuresPath, "utf8");
+    recorded = JSON.parse(text);
+  } catch {
+    return "missing";
+  }
+  if (!recorded || typeof recorded !== "object" || Array.isArray(recorded)) return "missing";
+  const parts = [];
+  const recordedGoldens = new Map(list(recorded.goldens).map((g) => [str(g?.path), str(g?.sha256)]));
+  const current = new Map(diskGoldens.map((g) => [g.path, g.sha256]));
+  const added = [...current.keys()].filter((p) => !recordedGoldens.has(p)).sort();
+  const removed = [...recordedGoldens.keys()].filter((p) => !current.has(p)).sort();
+  const changed = [...current.keys()].filter((p) => recordedGoldens.has(p) && recordedGoldens.get(p) !== current.get(p)).sort();
+  if (added.length) parts.push(`added ${added.join(", ")}`);
+  if (removed.length) parts.push(`removed ${removed.join(", ")}`);
+  if (changed.length) parts.push(`changed ${changed.join(", ")}`);
+  if (recorded.dna !== DNA_FORMAT) parts.push(`dna version ${JSON.stringify(recorded.dna ?? null)} is not the "${DNA_FORMAT}" this linter knows`);
+  if (!diskScope) return parts.length ? parts.join("; ") : null;
+
+  const recordedScope = isObj(recorded.scope) ? recorded.scope : {};
+  const scopeFields = ["writer", "form", "audience", "purpose"].filter((k) => recordedScope[k] !== diskScope[k]);
+  if (scopeFields.length) parts.push(`scope changed: ${scopeFields.join(", ")}`);
+  const features = measureFeatures(diskGoldens.map((g) => g.text));
+  if (!added.length && !removed.length && !changed.length) {
+    const recordedFeatures = isObj(recorded.features) ? recorded.features : {};
+    const keys = [...new Set([...Object.keys(features), ...Object.keys(recordedFeatures)])];
+    const differ = keys.filter((k) => JSON.stringify(features[k]) !== JSON.stringify(recordedFeatures[k]));
+    if (differ.length) parts.push(`features differ from a fresh measurement: ${differ.join(", ")}`);
+  }
+  if (!parts.length && text !== featuresText({ scope: diskScope, goldens: diskGoldens, features }).text) {
+    parts.push("the file is not byte for byte what `hyperspec dna measure` writes");
+  }
+  return parts.length ? parts.join("; ") : null;
+}
+
 function dnaFields(raw, d, here, idPrefix) {
   const out = [];
   if (!str(raw.writer)) out.push(f(1, `${idPrefix}-writer`, "fail", "writing.dna has no writer", "Add writer:."));
   const scope = isObj(raw.scope) ? raw.scope : {};
+  // scope-<field> is the spec's own writing.dna.scope, the id 0.4.0 shipped; scope-file-<field>
+  // (src/dna.mjs) is a scope folder's scope.md.
   if (!str(scope.form)) out.push(f(1, `${idPrefix}-scope-form`, "fail", "writing.dna.scope has no form", "Add scope.form:."));
   if (!str(scope.audience)) out.push(f(1, `${idPrefix}-scope-audience`, "fail", "writing.dna.scope has no audience", "Add scope.audience:."));
   if (!str(scope.purpose)) out.push(f(1, `${idPrefix}-scope-purpose`, "fail", "writing.dna.scope has no purpose", "Add scope.purpose:."));
   const rulesPath = str(raw.rules);
   if (!rulesPath) out.push(f(1, `${idPrefix}-rules`, "fail", "writing.dna has no rules", "Add rules: the path to the always-on writing style."));
   else out.push(...pathFindings(here, rulesPath, `${idPrefix}-rules`, "dna.rules", "Fix the path, or add the file."));
+
+  // scope_dir is optional, so its KEY being absent from writing.dna is never a finding (the
+  // whole scope_dir section below simply does not run). But a key that IS present with a
+  // placeholder-ish value (TODO, tbd, an empty string, ...) is a different situation: the operator
+  // wrote something and str() silently reads it as "not there", which would otherwise make a
+  // half-filled skeleton lint clean by accident. That gets its own finding, naming the value, and
+  // is why this check reads raw.scope_dir directly rather than through scopeDirRaw.
+  if (raw.scope_dir !== undefined && !str(raw.scope_dir)) {
+    out.push(f(1, `${idPrefix}-scope-dir`, "fail",
+      `writing.dna.scope_dir "${raw.scope_dir}" looks like a placeholder`,
+      "Point scope_dir: at a real scope folder (built with hyperspec dna init), or remove the field entirely; it is optional."));
+  }
+  const scopeDirRaw = str(raw.scope_dir);
+  const scopeDirAbs = scopeDirRaw ? here(scopeDirRaw) : null;
+  const disk = scopeDirRaw ? readScope(scopeDirAbs, { displayDir: scopeDirRaw }) : null;
+  const diskIds = new Set((disk?.findings ?? []).map((x) => x.id));
+  const goldensOutside = diskIds.has("writing-dna-goldens-outside");
+  const lexicalGoldens = scopeDirRaw ? here(join(scopeDirRaw, "goldens")) : null;
+  const realScope = scopeDirRaw ? realOrNull(scopeDirAbs) : null;
+  const realGoldens = realScope ? join(realScope, "goldens") : null;
+
   const goldens = list(raw.goldens);
   if (!goldens.length) out.push(f(1, `${idPrefix}-goldens`, "fail", "writing.dna has no goldens", "Add at least one golden under dna.goldens."));
   goldens.forEach((g, i) => {
@@ -148,7 +285,44 @@ function dnaFields(raw, d, here, idPrefix) {
     if (!p) out.push(f(1, `${idPrefix}-golden-${i}-path`, "fail", `dna.goldens[${i + 1}] has no path`, "Add path: to the golden."));
     else out.push(...pathFindings(here, p, `${idPrefix}-golden-${i}`, "golden", "Fix the path, or add the golden file."));
     if (!str(g?.why)) out.push(f(6, `${idPrefix}-golden-${i}-why`, "fail", `golden "${p || `#${i + 1}`}" has no why`, "Add why: what it shows that an adjective could not."));
+    // Checked only once the path resolves to a real file: a missing or non-file path is already
+    // reported above under test 6, and is not also a leak.
+    if (scopeDirRaw && p && pathKind(here, p) === "file") {
+      const reason = leakReason(lexicalGoldens, realGoldens, here(p));
+      // A goldens/ folder that resolves outside the scope already has its own finding, which
+      // names the cause for every golden listed through it.
+      const coveredByFolder = goldensOutside && isInsideDir(lexicalGoldens, here(p));
+      if (reason && !coveredByFolder) out.push(leakFinding(idPrefix, reason, p, i, scopeDirRaw));
+    }
   });
+
+  if (scopeDirRaw) {
+    const { scope: diskScope, goldens: diskGoldens, findings: diskFindings } = disk;
+    out.push(...diskFindings);
+
+    if (diskScope) {
+      scopeMismatch(out, idPrefix, scopeDirRaw, "writer", "writer", raw.writer, diskScope.writer);
+      scopeMismatch(out, idPrefix, scopeDirRaw, "form", "form", scope.form, diskScope.form);
+      scopeMismatch(out, idPrefix, scopeDirRaw, "audience", "audience", scope.audience, diskScope.audience);
+      scopeMismatch(out, idPrefix, scopeDirRaw, "purpose", "purpose", scope.purpose, diskScope.purpose);
+    }
+
+    // With the goldens folder unreadable or somewhere else, there is nothing to compare
+    // features.json against; that folder's own finding says what to fix first.
+    if (!goldensOutside && !diskIds.has("writing-dna-goldens-missing")) {
+      const stale = featuresStaleness(join(scopeDirAbs, "features.json"), diskScope, diskGoldens);
+      if (stale === "missing") {
+        out.push(f(6, `${idPrefix}-features-missing`, "fail",
+          `writing.dna.scope_dir "${scopeDirRaw}" has no features.json (or it is not valid JSON)`,
+          `Run \`hyperspec dna measure ${scopeDirRaw}\`.`));
+      } else if (stale) {
+        out.push(f(6, `${idPrefix}-features-stale`, "fail",
+          `writing.dna.scope_dir "${scopeDirRaw}"'s features.json is stale: ${stale}`,
+          `Run \`hyperspec dna measure ${scopeDirRaw}\` again.`));
+      }
+    }
+  }
+
   return out;
 }
 
@@ -193,6 +367,28 @@ function audienceFields(raw, d, here, idPrefix) {
   if (!list(raw.knows).some((x) => str(x))) out.push(f(1, `${idPrefix}-knows`, "fail", "writing.audience has no knows", "List at least one term the reader already has."));
   const reader = str(raw.reader);
   if (!READER_VALUES.includes(reader)) out.push(f(1, `${idPrefix}-reader`, "fail", `writing.audience.reader is "${reader || "(none)"}"`, "Set reader to person or agent."));
+
+  // terms (0.6, optional): the reader-may-not-know terms the check command's `terms` station
+  // checks are defined at first use. The KEY being absent is fine and does not change the
+  // audience block's completeness (the same "absence is 0.4/0.5 behavior" shape scope_dir and
+  // characters use elsewhere in this file): nothing below runs, and the block can still be
+  // complete with no terms: field at all. Present, though, it must be a list of real text: a
+  // scalar is named as not a list, an empty list fails as a whole (the "declared but empty" shape
+  // audience.knows already uses one line up), and each non-string, placeholder or empty entry is
+  // named on its own (mirroring the top-level `rejects` list's own item check in src/rules.mjs).
+  if (raw.terms !== undefined) {
+    if (!Array.isArray(raw.terms)) {
+      out.push(f(1, `${idPrefix}-terms`, "fail", "writing.audience.terms is not a list", "Write terms as a list, one term per line starting \"- \"."));
+    } else if (!raw.terms.length) {
+      out.push(f(1, `${idPrefix}-terms`, "fail", "writing.audience.terms is present but has no real entries", "List at least one term, or remove terms: entirely; it is optional."));
+    } else {
+      raw.terms.forEach((x, i) => {
+        if (x != null && typeof x !== "string") out.push(f(1, `${idPrefix}-terms`, "fail", `writing.audience.terms item ${i + 1} is not a plain string`, "Write each term as plain text, e.g. a word or short phrase."));
+        else if (!str(x)) out.push(f(1, `${idPrefix}-terms`, "fail", `writing.audience.terms item ${i + 1} is ${typeof x === "string" && x.trim() ? "a placeholder" : "empty"}`, "Replace it with the real term, or remove the item."));
+      });
+    }
+  }
+
   return out;
 }