@supersuit/hyperspec 0.1.0 → 0.3.0

package/src/template.mjs

@@ -1,8 +1,20 @@
+// A scalar left unquoted only when every YAML reader reads it back as the same text: it starts
+// with a letter or digit, holds only letters, digits, spaces and plain punctuation, and is not a
+// word YAML turns into null, a boolean or a number. Anything else is written as a JSON string,
+// which is also a valid YAML double-quoted scalar.
+const PLAIN = /^[A-Za-z0-9][A-Za-z0-9 _.,'()/-]*$/;
+const RESOLVES = /^(null|~|true|false|yes|no|on|off|y|n|[-+]?(\d[\d_]*)?\.?\d+([eE][-+]?\d+)?|0x[0-9a-f]+|0o[0-7]+|\.inf|\.nan)$/i;
+// Exported so any other init-time template (writing-template.mjs's writingTemplate, and whatever
+// profile templates come after it) quotes titles, kinds and other free-text scalars the same way,
+// rather than re-deriving this regex pair.
+export const scalar = (v) => (PLAIN.test(v) && !/\s$/.test(v) && !RESOLVES.test(v) ? v : JSON.stringify(v));
+
 export function template({ title = "Untitled", kind = "document" } = {}) {
+  const heading = String(title).replace(/\s+/g, " ").trim();
   return `---
 hyperspec: "0.1"
-title: ${title}
-kind: ${kind}
+title: ${scalar(String(title))}
+kind: ${scalar(String(kind))}
 decisions:
   - id: audience
     state: open
@@ -22,6 +34,6 @@ improvement:
   ledger: runs.jsonl
 ---
 
-# ${title}
+# ${heading}
 `;
 }

package/src/writer.mjs

@@ -0,0 +1,125 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { sha256 } from "./hash.mjs";
+import { writeFileAtomic } from "./fsutil.mjs";
+import { storeRoot, putBlob, getBlob } from "./blobs.mjs";
+import { checkRecipe, readRecipe, stageKey, writeRecipe } from "./recipe.mjs";
+import { loadSpec } from "./load.mjs";
+
+// What every outcome factory calls at the end of a run to record what it made, from what, and
+// how. output and spec are paths, resolved against process.cwd(); every path stored inside the
+// recipe (output.path, spec.path, each input's path) is relative to the recipe file's own
+// directory, per the recipe file convention in SPEC.md.
+export function startRecipe({ output, factory, spec, clicker, store } = {}) {
+  const outputAbs = resolve(process.cwd(), output);
+  const recipePath = `${outputAbs}.recipe.json`;
+  const recipeDir = dirname(recipePath);
+  const root = storeRoot({ from: recipeDir, store });
+
+  const specLoaded = loadSpec(spec);
+  if (specLoaded.error) throw new Error(specLoaded.error);
+  const specBytes = readFileSync(specLoaded.path);
+  const specHash = putBlob(root, specBytes);
+  // spec.authors is id -> author across decisions and requirements together; the two arrays
+  // share one id namespace here (every field is traced back to its source), so an id reused
+  // across them is a collision, not a silent overwrite, whether or not the authors agree.
+  const authors = {};
+  for (const d of [...(specLoaded.data.decisions ?? []), ...(specLoaded.data.requirements ?? [])]) {
+    if (!d || typeof d.id !== "string") continue;
+    if (Object.prototype.hasOwnProperty.call(authors, d.id)) {
+      throw new Error(`spec id ${d.id} is used twice; ids must be unique across decisions and requirements`);
+    }
+    // null rather than undefined, which JSON would drop: recipe check then names the id.
+    authors[d.id] = typeof d.author === "string" && d.author.trim() ? d.author : null;
+  }
+
+  const recipe = {
+    recipe: "0.1",
+    created: new Date().toISOString(),
+    output: { path: relative(recipeDir, outputAbs), sha256: null },
+    factory,
+    spec: { path: relative(recipeDir, specLoaded.path), sha256: specHash, authors },
+    inputs: [],
+    stages: [],
+    clicker,
+    approver: null,
+    parent: null,
+    change: null,
+  };
+
+  return {
+    // Stores the file's bytes as a blob now and records {name, path, sha256, order}. order is
+    // assigned by call order, starting at 1. A duplicate name throws.
+    input(name, path) {
+      if (recipe.inputs.some((i) => i.name === name)) throw new Error(`duplicate input name: ${name}`);
+      const abs = resolve(process.cwd(), path);
+      const bytes = readFileSync(abs);
+      const hex = putBlob(root, bytes);
+      const entry = { name, path: relative(recipeDir, abs), sha256: hex, order: recipe.inputs.length + 1 };
+      recipe.inputs.push(entry);
+      return entry;
+    },
+
+    // Stores output (string or Buffer) as a blob, computes key with stageKey, and validates reads
+    // by delegating to stageKey/resolveReads (an unknown ref throws). A duplicate id throws too,
+    // since resolveReads resolves a stage: ref by id and a duplicate would make that ambiguous.
+    stage({ id, reads, model, output: stageOutput, verdict } = {}) {
+      if (!id) throw new Error("stage needs an id");
+      if (recipe.stages.some((s) => s.id === id)) throw new Error(`duplicate stage id: ${id}`);
+      const hex = putBlob(root, stageOutput);
+      const index = recipe.stages.length;
+      // The key must be computed from exactly what the recipe file will hold. A Date, an
+      // undefined, or anything else JSON writes differently from how it hashes would otherwise
+      // produce a recipe that fails its own key check the moment it is read back.
+      const entry = { id, reads: reads ?? [], model: asWritten(model ?? undefined), key: undefined, output: { sha256: hex }, verdict: asWritten(verdict) };
+      recipe.stages.push(entry);
+      try {
+        entry.key = stageKey(recipe, index);
+      } catch (e) {
+        recipe.stages.pop();
+        throw e;
+      }
+      return entry;
+    },
+
+    // Writes the output file from the last stage's blob if it is absent, or checks the file on
+    // disk against it if present (throwing on a mismatch: the output on disk must be what the
+    // recipe says). Writes the recipe file and returns checkRecipe's findings; an unapproved
+    // recipe returning only the approver fail is expected, not an error. Refuses a stage-less
+    // recipe before writing anything (neither the output file nor the recipe file): a recipe
+    // with no stages has nothing to have made, so finishing one would write an "approved" recipe
+    // for content that does not exist.
+    finish({ approver = null } = {}) {
+      if (!recipe.stages.length) throw new Error("a recipe needs at least one stage");
+      recipe.approver = approver;
+      const last = recipe.stages[recipe.stages.length - 1];
+      recipe.output.sha256 = last.output.sha256;
+      if (existsSync(outputAbs)) {
+        const onDisk = readFileSync(outputAbs);
+        if (sha256(onDisk) !== last.output.sha256) {
+          throw new Error(`${output} does not match the recipe's last stage output`);
+        }
+      } else {
+        writeFileAtomic(outputAbs, getBlob(root, last.output.sha256));
+      }
+      writeRecipe(recipePath, recipe);
+      return { path: recipePath, findings: checkRecipe(asWritten(recipe)) };
+    },
+  };
+}
+
+// Rereads the recipe, sets approver, rewrites it, and returns the new findings.
+export function approve(recipePath, by) {
+  const { data, error } = readRecipe(recipePath);
+  if (error) throw new Error(error);
+  data.approver = by;
+  writeRecipe(recipePath, data);
+  return checkRecipe(data);
+}
+
+// A value exactly as the recipe file will hold it: what JSON.stringify writes, read back.
+function asWritten(value) {
+  if (value === undefined) return undefined;
+  const text = JSON.stringify(value);
+  return text === undefined ? undefined : JSON.parse(text);
+}

package/src/writing-fields.mjs

@@ -0,0 +1,317 @@
+// Field-level rules for the nine writing blocks. src/writing.mjs owns the generic shape (a block
+// is present or openly deferred, and every present block carries a check, a source and an
+// author); this file owns what is INSIDE each block once it is present, block by block, as
+// WRITING.md's schema documents it. Every finding here still reports under one of the nine core
+// tests, with an id prefixed writing-<block>- (or writing-characters-<index>- for a character
+// entry), so writing.mjs's blockStatus (which reads findings by id prefix, not by calling back
+// into this file) keeps attributing brokenness correctly with no change on its side.
+//
+// Scope, stated once rather than re-argued at each block: every schema field not marked optional
+// is required, and its absence fails test 1 (a missing required field), unless a more specific
+// test owns that exact violation (a golden's why is test 6, goal.conditions is test 2, and so on).
+//
+// Paths (materials/dna/audience/... path-bearing fields) resolve the same way examples do
+// elsewhere in this linter: relative to the spec file. That resolver (here) is supplied by
+// writing.mjs, which already has spec.dir in scope; this file never touches spec directly.
+//
+// A character's speech.uses, speech.never, wants, fears, hides and arc_state are required
+// (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 { str } from "./placeholder.mjs";
+
+const f = (test, id, severity, message, fix) => ({ test, id, severity, message, fix });
+const list = (v) => (Array.isArray(v) ? v : []);
+const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+// "file", "other" (a directory or a device), or null when nothing is there at all — the same
+// three-way classification the core examples rule uses (src/rules.mjs's kind()), so a real
+// directory is reported as "is not a file" rather than the misleading "does not exist".
+const pathKind = (here, p) => { try { return statSync(here(p)).isFile() ? "file" : "other"; } catch { return null; } };
+// The two-finding shape every path-bearing field in this file shares: idBase-missing when
+// nothing is there, idBase-not-file when something is there but it is not a file (a directory).
+// subject is the human-readable name used in the message ("material", "dna.rules", "golden",
+// "character ... entity"); fixHint is the same for both branches, since the fix is the same path
+// edit either way.
+function pathFindings(here, p, idBase, subject, fixHint) {
+  const k = pathKind(here, p);
+  if (!k) return [f(6, `${idBase}-missing`, "fail", `${subject} "${p}" does not exist`, fixHint)];
+  if (k !== "file") return [f(6, `${idBase}-not-file`, "fail", `${subject} "${p}" is not a file`, fixHint)];
+  return [];
+}
+
+const TRUST_VALUES = ["raw", "considered", "verified"];
+const READER_VALUES = ["person", "agent"];
+const CHANGE_KINDS = ["belief", "action", "feeling"];
+const STANCE_VALUES = ["peer", "mentor", "witness", "guide"];
+const IDENTITY_SHAPE = /^(role|character):(.+)$/;
+
+// ---------------------------------------------------------------- 1. materials ----------------
+
+function materialsFields(raw, d, here, idPrefix) {
+  const out = [];
+  const items = list(raw.items);
+  const seen = new Set();
+  // A third (or later) item sharing an already-duplicated id must not produce a second,
+  // textually identical finding: report each duplicated id once, the first time it repeats.
+  const reportedDup = new Set();
+  items.forEach((it, i) => {
+    const id = str(it?.id);
+    const tag = id || `#${i + 1}`;
+    if (!id) out.push(f(1, `${idPrefix}-item-${i}-id`, "fail", `materials item ${tag} has no id`, "Give it a short id, e.g. m1."));
+    else if (seen.has(id)) {
+      if (!reportedDup.has(id)) out.push(f(1, `${idPrefix}-item-id`, "fail", `materials id "${id}" is used twice`, "Ids must be unique across materials.items; rename one."));
+      reportedDup.add(id);
+    }
+    seen.add(id);
+    if (!str(it?.produced_by)) out.push(f(1, `${idPrefix}-item-${i}-produced-by`, "fail", `material ${tag} does not say who produced it`, "Add produced_by:."));
+    if (!str(it?.captured)) out.push(f(1, `${idPrefix}-item-${i}-captured`, "fail", `material ${tag} does not say when it was captured`, "Add captured:."));
+    if (!str(it?.how)) out.push(f(1, `${idPrefix}-item-${i}-how`, "fail", `material ${tag} does not say how it was captured`, "Add how:."));
+    const trust = str(it?.trust);
+    if (!TRUST_VALUES.includes(trust)) out.push(f(1, `${idPrefix}-item-${i}-trust`, "fail", `material ${tag} has trust "${trust || "(none)"}"`, "Set trust to raw, considered or verified."));
+    const p = str(it?.path);
+    if (!p) out.push(f(1, `${idPrefix}-item-${i}-path`, "fail", `material ${tag} has no path`, "Add path: to the material."));
+    else out.push(...pathFindings(here, p, `${idPrefix}-item-${i}-path`, "material", "Fix the path, or add the material file."));
+  });
+  return out;
+}
+
+// ---------------------------------------------------------------- 2. dna ----------------------
+
+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 : {};
+  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."));
+  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) => {
+    const p = str(g?.path);
+    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."));
+  });
+  return out;
+}
+
+// ---------------------------------------------------------------- 3. persona ------------------
+
+function personaFields(raw, d, here, idPrefix) {
+  const out = [];
+  const identity = str(raw.identity);
+  if (!identity) {
+    out.push(f(1, `${idPrefix}-identity`, "fail", "writing.persona has no identity", "Add identity: self, role:<name>, or character:<id>."));
+  } else if (identity !== "self") {
+    const m = IDENTITY_SHAPE.exec(identity);
+    if (!m || !m[2].trim()) {
+      out.push(f(1, `${idPrefix}-identity`, "fail", `writing.persona.identity "${identity}" is not self, role:<name> or character:<id>`, "Set identity to self, role:<name>, or character:<id>."));
+    } else if (m[1] === "character") {
+      const cid = m[2].trim();
+      const chars = list(d.writing?.characters);
+      if (!chars.some((c) => str(c?.id) === cid)) {
+        out.push(f(1, `${idPrefix}-identity`, "fail", `writing.persona.identity names character "${cid}", which is not in writing.characters`, "Point identity at a character id that exists in writing.characters."));
+      }
+    }
+  }
+  const stance = str(raw.stance);
+  if (!stance) out.push(f(1, `${idPrefix}-stance`, "fail", "writing.persona has no stance", "Add stance: peer, mentor, witness or guide."));
+  else if (!STANCE_VALUES.includes(stance)) out.push(f(1, `${idPrefix}-stance`, "warn", `writing.persona.stance "${stance}" is outside peer, mentor, witness, guide`, "Consider peer, mentor, witness or guide."));
+  if (!list(raw.may_assert).some((x) => str(x))) out.push(f(1, `${idPrefix}-may-assert`, "fail", "writing.persona has no may_assert", "List at least one thing the persona may assert."));
+  if (!list(raw.will_not_say).some((x) => str(x))) out.push(f(5, `${idPrefix}-will-not-say`, "fail", "writing.persona.will_not_say is empty", "List at least one thing the persona will not say."));
+  const factsFrom = str(raw.facts_from);
+  if (factsFrom !== "sources") out.push(f(5, `${idPrefix}-facts-from`, "fail", `writing.persona.facts_from is "${factsFrom || "(none)"}", not "sources"`, "Set facts_from: sources."));
+  return out;
+}
+
+// ---------------------------------------------------------------- 4. audience -----------------
+
+const AUDIENCE_REQUIRED = ["who", "funnel_now", "believes_now", "wants", "reads_on"];
+
+function audienceFields(raw, d, here, idPrefix) {
+  const out = [];
+  for (const field of AUDIENCE_REQUIRED) {
+    if (!str(raw[field])) out.push(f(1, `${idPrefix}-${field.replace(/_/g, "-")}`, "fail", `writing.audience has no ${field}`, `Add ${field}:.`));
+  }
+  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."));
+  return out;
+}
+
+// ---------------------------------------------------------------- 5. goal ---------------------
+
+const GOAL_REQUIRED = ["from", "to", "next_if_worked"];
+
+function goalFields(raw, d, here, idPrefix) {
+  const out = [];
+  for (const field of GOAL_REQUIRED) {
+    if (!str(raw[field])) out.push(f(1, `${idPrefix}-${field.replace(/_/g, "-")}`, "fail", `writing.goal has no ${field}`, `Add ${field}:.`));
+  }
+  const change = isObj(raw.change) ? raw.change : {};
+  const kind = str(change.kind);
+  if (!CHANGE_KINDS.includes(kind)) out.push(f(1, `${idPrefix}-change-kind`, "fail", `writing.goal.change.kind is "${kind || "(none)"}"`, "Set change.kind to belief, action or feeling."));
+  if (!str(change.text)) out.push(f(1, `${idPrefix}-change-text`, "fail", "writing.goal.change has no text", "Add change.text:."));
+
+  const listed = list(raw.conditions).map(str).filter(Boolean);
+  // Distinct ids only: five copies of one requirement are one condition, not five.
+  const conditions = [...new Set(listed)];
+  const repeated = [...new Set(listed.filter((cid, i) => listed.indexOf(cid) !== i))];
+  repeated.forEach((cid) => {
+    out.push(f(2, `${idPrefix}-conditions-duplicate`, "fail", `writing.goal.conditions lists "${cid}" more than once`, "List each requirement id once."));
+  });
+  if (conditions.length < 5 || conditions.length > 10) {
+    out.push(f(2, `${idPrefix}-conditions-count`, "fail", `writing.goal.conditions has ${conditions.length} distinct ids, outside 5 to 10`, "List 5 to 10 distinct requirement ids under goal.conditions."));
+  }
+  const reqIds = new Set(list(d.requirements).map((r) => str(r?.id)).filter(Boolean));
+  conditions.forEach((cid) => {
+    if (!reqIds.has(cid)) out.push(f(2, `${idPrefix}-conditions-unknown`, "fail", `writing.goal.conditions names "${cid}", which is not a requirement id`, "Point conditions at ids that exist under requirements:."));
+  });
+  return out;
+}
+
+// ---------------------------------------------------------------- 6. form ---------------------
+
+function formFields(raw, d, here, idPrefix) {
+  const out = [];
+  if (!str(raw.name)) out.push(f(1, `${idPrefix}-name`, "fail", "writing.form has no name", "Add name:."));
+  const length = isObj(raw.length) ? raw.length : {};
+  const minStr = str(length.min);
+  const maxStr = str(length.max);
+  // The YAML reader returns every scalar as a string, min: 600 included, so a numeric field is
+  // parsed explicitly here rather than compared as a closed-set string; a non-numeric length is a
+  // test 1 fail like any other malformed required field.
+  // Both bounds are whole numbers of at least 1: a length of zero, a negative length or half a
+  // word describes no piece anyone could write.
+  const positiveInt = (s) => /^\d+$/.test(s) && Number(s) >= 1;
+  const min = Number(minStr);
+  const max = Number(maxStr);
+  const minOk = positiveInt(minStr);
+  const maxOk = positiveInt(maxStr);
+  if (!minOk) out.push(f(1, `${idPrefix}-length-min`, "fail", `writing.form.length.min "${minStr || "(none)"}" is not a whole number of at least 1`, "Set length.min to a whole number, 1 or more."));
+  if (!maxOk) out.push(f(1, `${idPrefix}-length-max`, "fail", `writing.form.length.max "${maxStr || "(none)"}" is not a whole number of at least 1`, "Set length.max to a whole number, 1 or more."));
+  if (minOk && maxOk && min > max) out.push(f(1, `${idPrefix}-length-range`, "fail", `writing.form.length.min (${min}) is greater than length.max (${max})`, "Set min to no more than max."));
+  if (!str(length.unit)) out.push(f(1, `${idPrefix}-length-unit`, "fail", "writing.form.length has no unit", "Add length.unit:, e.g. words."));
+  if (!list(raw.required_parts).some((x) => str(x))) out.push(f(1, `${idPrefix}-required-parts`, "fail", "writing.form has no required_parts", "List at least one required part."));
+  return out;
+}
+
+// ---------------------------------------------------------------- 7. spine --------------------
+
+function spineFields(raw, d, here, idPrefix) {
+  const out = [];
+  if (!str(raw.kind)) out.push(f(1, `${idPrefix}-kind`, "fail", "writing.spine has no kind", "Add kind:."));
+  const claims = list(raw.claims);
+  // A repeated claim id is reported once per id and counts once toward 3 to 7: three copies of
+  // one claim are one claim. A claim with no id still counts (its own finding says what is wrong).
+  const seenClaims = new Set();
+  const reportedClaims = new Set();
+  let distinct = 0;
+  claims.forEach((c) => {
+    const id = str(c?.id);
+    if (id && seenClaims.has(id)) {
+      if (!reportedClaims.has(id)) out.push(f(1, `${idPrefix}-claim-id`, "fail", `spine claim id "${id}" is used twice`, "Ids must be unique across spine.claims; rename one, or merge the claims."));
+      reportedClaims.add(id);
+      return;
+    }
+    if (id) seenClaims.add(id);
+    distinct += 1;
+  });
+  if (distinct < 3 || distinct > 7) out.push(f(1, `${idPrefix}-claims-count`, "fail", `writing.spine has ${distinct} distinct claims, outside 3 to 7`, "List 3 to 7 claims, each with its own id, under spine.claims."));
+  const materialIds = new Set(list(d.writing?.materials?.items).map((m) => str(m?.id)).filter(Boolean));
+  claims.forEach((c, i) => {
+    const cid = str(c?.id) || `#${i + 1}`;
+    if (!str(c?.id)) out.push(f(1, `${idPrefix}-claim-${i}-id`, "fail", `spine claim ${cid} has no id`, "Give it a short id, e.g. c1."));
+    if (!str(c?.text)) out.push(f(1, `${idPrefix}-claim-${i}-text`, "fail", `spine claim "${cid}" has no text`, "Add text: to the claim."));
+    const refs = list(c?.materials).map(str).filter(Boolean);
+    if (!refs.length) {
+      out.push(f(4, `${idPrefix}-claim-${i}-materials`, "fail", `spine claim "${cid}" has no materials`, "Point materials: at one or more material ids."));
+    } else {
+      refs.forEach((ref) => {
+        const mid = ref.split("#")[0];
+        if (!materialIds.has(mid)) out.push(f(4, `${idPrefix}-claim-${i}-materials-unknown`, "fail", `spine claim "${cid}" points at material "${ref}", which is not in writing.materials.items`, "Point materials: at an id that exists in writing.materials.items."));
+      });
+    }
+  });
+  return out;
+}
+
+// ---------------------------------------------------------------- 8. sources ------------------
+
+function sourcesFields(raw, d, here, idPrefix) {
+  const out = [];
+  if (!str(raw.ledger)) out.push(f(1, `${idPrefix}-ledger`, "fail", "writing.sources has no ledger", "Add ledger: the path each run's claims are checked against."));
+  // sources.ledger is a path that need not exist before drafting: no existence check here, unlike
+  // every other path in this file.
+  const unsourced = str(raw.unsourced_claim);
+  if (!["fail", "warn"].includes(unsourced)) {
+    out.push(f(1, `${idPrefix}-unsourced-claim`, "fail", `writing.sources.unsourced_claim is "${unsourced || "(none)"}"`, "Set unsourced_claim to fail or warn."));
+  } else if (unsourced === "warn") {
+    out.push(f(1, `${idPrefix}-unsourced-claim-warn`, "warn", "writing.sources.unsourced_claim is warn; an unsourced claim will only warn, not fail the draft", "Set unsourced_claim: fail if an unsourced claim should block the draft."));
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- 9. characters ---------------
+
+// One character entry, called per-entry from writing.mjs the same way checkOwner is. idPrefix is
+// already writing-characters-<index>, matching the block-attribution prefix blockStatus expects.
+function characterFields(c, here, idPrefix) {
+  const out = [];
+  const tag = str(c?.id) || "?";
+  if (!str(c?.id)) out.push(f(1, `${idPrefix}-id`, "fail", "character has no id", "Give it a short id."));
+
+  // Raw array length, matching dnaFields' goldens.length check: a present-but-malformed entry
+  // (missing by or knows) must not ALSO trigger "has no knowledge" — that's only true when the
+  // list is literally empty.
+  const knowledge = list(c?.knowledge);
+  if (!knowledge.length) out.push(f(1, `${idPrefix}-knowledge`, "fail", `character "${tag}" has no knowledge`, "Add at least one { by, knows } entry under knowledge."));
+  knowledge.forEach((k, i) => {
+    if (!str(k?.by)) out.push(f(1, `${idPrefix}-knowledge-${i}-by`, "fail", `character "${tag}" knowledge entry ${i + 1} has no by`, "Add by: to the knowledge entry."));
+    if (!str(k?.knows)) out.push(f(1, `${idPrefix}-knowledge-${i}-knows`, "fail", `character "${tag}" knowledge entry ${i + 1} has no knows`, "Add knows: to the knowledge entry."));
+  });
+
+  if (!list(c?.golden_lines).some((x) => str(x))) out.push(f(6, `${idPrefix}-golden-lines`, "fail", `character "${tag}" has no golden_lines`, "Add at least one golden line."));
+  if (!list(c?.rejected_lines).some((x) => str(x))) out.push(f(6, `${idPrefix}-rejected-lines`, "fail", `character "${tag}" has no rejected_lines`, "Add at least one rejected line."));
+  // A line cannot be both how the character speaks and how they never would: the consistency
+  // check has nothing to grade against. Compared trimmed and case-folded.
+  const fold = (x) => str(x).toLowerCase();
+  const golden = new Set(list(c?.golden_lines).map(fold).filter(Boolean));
+  const clash = list(c?.rejected_lines).map(fold).filter((x) => x && golden.has(x));
+  if (clash.length) out.push(f(6, `${idPrefix}-line-conflict`, "fail", `character "${tag}" has "${clash[0]}" as both a golden and a rejected line`, "Remove the line from one of golden_lines or rejected_lines."));
+
+  // speech.uses, speech.never, wants, fears, hides and arc_state are what make dialogue
+  // specifiable. relationships is deliberately not required here: a character may genuinely
+  // relate to no one yet.
+  const speech = isObj(c?.speech) ? c.speech : {};
+  if (!list(speech.uses).some((x) => str(x))) out.push(f(1, `${idPrefix}-speech-uses`, "fail", `character "${tag}" speech.uses is empty`, "List at least one thing the character says."));
+  if (!list(speech.never).some((x) => str(x))) out.push(f(1, `${idPrefix}-speech-never`, "fail", `character "${tag}" speech.never is empty`, "List at least one thing the character never says."));
+  if (!str(c?.wants)) out.push(f(1, `${idPrefix}-wants`, "fail", `character "${tag}" has no wants`, "Add wants:."));
+  if (!str(c?.fears)) out.push(f(1, `${idPrefix}-fears`, "fail", `character "${tag}" has no fears`, "Add fears:."));
+  if (!str(c?.hides)) out.push(f(1, `${idPrefix}-hides`, "fail", `character "${tag}" has no hides`, "Add hides:."));
+  if (!str(c?.arc_state)) out.push(f(1, `${idPrefix}-arc-state`, "fail", `character "${tag}" has no arc_state`, "Add arc_state:."));
+
+  const entity = str(c?.entity);
+  if (entity) out.push(...pathFindings(here, entity, `${idPrefix}-entity`, `character "${tag}" entity`, "Fix the path, or remove entity."));
+
+  return out;
+}
+
+// The eight object blocks' field rules, keyed by block name. characters is a list and is called
+// per-entry (characterFields) directly from writing.mjs, not through this map.
+export const BLOCK_FIELD_RULES = Object.freeze({
+  materials: materialsFields,
+  dna: dnaFields,
+  persona: personaFields,
+  audience: audienceFields,
+  goal: goalFields,
+  form: formFields,
+  spine: spineFields,
+  sources: sourcesFields,
+});
+
+export { characterFields };

package/src/writing-template.mjs

@@ -0,0 +1,192 @@
+// The writing profile's `hyperspec init --profile writing` skeleton.
+//
+// Every required writing block appears in full, in schema order, with every field present as a
+// placeholder value. An operator opening the file is owed the shape of every block inline, not a
+// pointer to go read the schema elsewhere. dna, persona, audience and goal also carry an open
+// decision (id writing-<block>, the deferral id writing.mjs knows) naming the question that has
+// to be answered before the placeholder means anything. The decision and the shape do not
+// conflict: the placeholder content already fails its own field rules, so the decision never
+// changes whether the spec passes, only what the operator is told to go decide.
+//
+// Every placeholder scalar in this file is the bare word "TODO". That is load-bearing: str() in
+// src/placeholder.mjs treats a value that IS a placeholder word as blank, so every presence check
+// on every field here fails on its own, without this file having to pick a field to break per
+// block. Without that rule the character block, whose checks are all presence checks, would lint
+// clean the moment init wrote it.
+//
+// init with no --profile never imports or calls this file: template.mjs's own template() is
+// untouched, so a bare init is still byte-for-byte what it always was.
+import { scalar } from "./template.mjs";
+
+const DECISION_QUESTIONS = Object.freeze({
+  dna: "whose voice is this, scoped to what form, audience and purpose, and which goldens define it?",
+  persona: "who does the piece speak as, what may it assert, and what will it never say?",
+  audience: "who reads this, what do they already believe, and what do they want when they arrive?",
+  goal: "what belief, action or feeling should move, and which requirements would prove it did?",
+});
+
+// Schema order (writing.mjs's BLOCKS): materials, dna, persona, audience, goal, form, spine,
+// sources, characters. These four get an open decision in ADDITION to their placeholder block,
+// because they are the ones that need real judgment before the placeholder means anything; every
+// other required block gets only the placeholder.
+const DECISION_BLOCKS = ["dna", "persona", "audience", "goal"];
+
+function deferredDecision(block) {
+  return `  - id: writing-${block}
+    state: open
+    question: ${scalar(DECISION_QUESTIONS[block])}
+    source: hyperspec init --profile writing
+    author: agent:hyperspec-init
+    chosen_by: agent`;
+}
+
+const CHARACTER_BLOCK = `
+  characters:
+    - id: TODO
+      speech:
+        uses:
+          - TODO
+        never:
+          - TODO
+        rhythm: TODO
+      wants: TODO
+      fears: TODO
+      hides: TODO
+      knowledge:
+        - by: TODO
+          knows: TODO
+      arc_state: TODO
+      golden_lines:
+        - TODO
+      rejected_lines:
+        - TODO
+      check:
+        rubric: TODO
+      source: TODO
+      author: TODO`;
+
+export function writingTemplate({ title = "Untitled", form = "essay", fiction = false } = {}) {
+  const heading = String(title).replace(/\s+/g, " ").trim();
+  const kind = String(form || "essay");
+  const decisions = DECISION_BLOCKS.map(deferredDecision).join("\n");
+  const characters = fiction ? CHARACTER_BLOCK : "";
+
+  return `---
+hyperspec: "0.1"
+title: ${scalar(String(title))}
+kind: ${scalar(kind)}
+profile: writing
+decisions:
+${decisions}
+requirements: []
+rejects: []
+examples: []
+resume:
+  next_action: answer the open decisions, then fill in every writing block below
+feedback:
+  issues: ""
+  fork: ""
+improvement:
+  ledger: runs.jsonl
+writing:
+  materials:
+    items:
+      - id: m1
+        path: materials/TODO.md
+        produced_by: TODO
+        captured: TODO
+        how: TODO
+        trust: TODO
+    check:
+      station: TODO
+    source: TODO
+    author: TODO
+  dna:
+    writer: TODO
+    scope:
+      form: TODO
+      audience: TODO
+      purpose: TODO
+    rules: TODO
+    goldens:
+      - path: goldens/TODO.md
+        why: TODO
+    check:
+      rubric: TODO
+    source: TODO
+    author: TODO
+  persona:
+    identity: TODO
+    stance: TODO
+    may_assert:
+      - TODO
+    will_not_say:
+      - TODO
+    facts_from: TODO
+    check:
+      rubric: TODO
+    source: TODO
+    author: TODO
+  audience:
+    who: TODO
+    funnel_now: TODO
+    knows:
+      - TODO
+    believes_now: TODO
+    wants: TODO
+    reads_on: TODO
+    reader: TODO
+    check:
+      station: TODO
+      rubric: TODO
+    source: TODO
+    author: TODO
+  goal:
+    from: TODO
+    to: TODO
+    next_if_worked: TODO
+    change:
+      kind: TODO
+      text: TODO
+    conditions:
+      - TODO
+    check:
+      rubric: TODO
+    source: TODO
+    author: TODO
+  form:
+    name: ${scalar(kind)}
+    length:
+      min: TODO
+      max: TODO
+      unit: TODO
+    required_parts:
+      - TODO
+    stations: []
+    check:
+      station: TODO
+    source: TODO
+    author: TODO
+  spine:
+    kind: TODO
+    claims:
+      - id: c1
+        text: TODO
+        materials: [m1]
+    check:
+      rubric: TODO
+    source: TODO
+    author: TODO
+  sources:
+    ledger: TODO.claims.jsonl
+    unsourced_claim: TODO
+    check:
+      station: TODO
+    source: TODO
+    author: TODO${characters}
+fiction: ${fiction ? "true" : "false"}
+---
+
+# ${heading}
+`;
+}