@supersuit/hyperspec 0.1.0 → 0.3.0

package/src/regenerate.mjs

@@ -0,0 +1,318 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { sha256 } from "./hash.mjs";
+import { getBlob, putBlob, storeRoot } from "./blobs.mjs";
+import { insideDir, writeFileAtomic } from "./fsutil.mjs";
+import { readRecipe, resolveReads, stageKey, writeRecipe } from "./recipe.mjs";
+
+const present = (v) => typeof v === "string" && v.trim().length > 0;
+const CHANGE_KEYS = ["addInput", "swapInput", "factoryVersion"];
+const RUNNER_MAX_BUFFER = 512 * 1024 * 1024;
+
+// Spec requirement `regenerate`: a recipe plus exactly ONE named change (a new input, a swapped
+// input, or a newer factory version) makes a child recipe that names its parent and the change.
+// Only the stages downstream of the change rerun; every other stage reuses its recorded output.
+//
+// Reuse is PROVEN, never assumed: a stage is reused only when its key, recomputed from the
+// child's hashes, equals the key the parent recorded for it, and only once its recorded output
+// blob re-hashes to what the parent claims, and only if the parent's recorded key matches the
+// parent's own record. A stage whose key differs reruns. With a runner that is decided per stage
+// at run time, after upstream reruns have produced their real bytes, so a reader whose key is
+// unchanged is reused. Without one, every transitive reader of a rerun stage is pending,
+// since its reads are unknown (transitive readers, not every later stage).
+//
+// hyperspec never calls a model. Rerun stages are run by `run`, a shell command the caller
+// supplies; without one the child is written with those stages pending.
+//
+// Nothing is written until the outcome is known: new input bytes and rerun outputs are held in
+// memory, and only land in the blob store (with the output file and the child recipe) once every
+// stage has run, or, with no runner, once the pending plan is settled. The parent recipe, its
+// output and its blobs are only ever read.
+export function regenerate(parentRecipePath, { out, clicker, change, run, changeText, store } = {}) {
+  const usage = (error) => ({ ok: false, usage: true, error, childRecipe: null, plan: [], pending: false, failedVerdicts: [] });
+  const failed = (error, extra = {}) => ({ ok: false, error, childRecipe: null, plan: [], pending: false, failedVerdicts: [], ...extra });
+
+  // ---- Options -------------------------------------------------------------------------------
+  const changeKeys = change && typeof change === "object" ? Object.keys(change).filter((k) => change[k] !== undefined) : [];
+  if (changeKeys.length !== 1 || !CHANGE_KEYS.includes(changeKeys[0])) {
+    return usage("exactly one change is required: an added input, a swapped input, or a factory version");
+  }
+  if (!present(clicker)) return usage("clicker is required");
+  if (!present(out)) return usage("out is required");
+
+  // ---- Parent ----------------------------------------------------------------------------------
+  const parentAbs = resolve(process.cwd(), parentRecipePath);
+  const loaded = readRecipe(parentAbs);
+  if (loaded.error) return usage(loaded.error);
+  const parentBytes = readFileSync(parentAbs);
+  const { data: parent, dir: parentDir } = loaded;
+  const parentStages = Array.isArray(parent.stages) ? parent.stages : [];
+  const parentInputs = Array.isArray(parent.inputs) ? parent.inputs : [];
+  if (parentStages.length === 0) return usage("the parent recipe has no stages");
+  if (!present(parent.spec?.sha256)) return usage("the parent recipe has no spec.sha256");
+
+  // The parent recipe is a plain JSON file, so its output.path is not trusted blind: one naming a
+  // place outside its own directory is refused rather than compared against (same rule as reproduce).
+  const parentOutputPath = parent.output?.path;
+  if (present(parentOutputPath) && !insideDir(parentDir, parentOutputPath)) {
+    return usage("the parent recipe's output path escapes its recipe directory");
+  }
+
+  // ---- Out -------------------------------------------------------------------------------------
+  const outAbs = resolve(process.cwd(), out);
+  const childRecipePath = `${outAbs}.recipe.json`;
+  const childDir = dirname(outAbs);
+  if (present(parentOutputPath) && resolve(parentDir, parentOutputPath) === outAbs) {
+    return usage(`${out} is the parent's output; the child needs its own path`);
+  }
+  if (existsSync(outAbs)) return usage(`${out} already exists; refusing to overwrite it`);
+  if (existsSync(childRecipePath)) return usage(`${childRecipePath} already exists; refusing to overwrite it`);
+  if (!isDir(childDir)) return usage(`directory ${childDir} does not exist`);
+
+  const childRoot = storeRoot({ from: childDir, store });
+  const parentRoot = storeRoot({ from: parentDir, store });
+  const held = new Map(); // hex -> Buffer, written to the store only once the outcome is known
+
+  // ---- The child, with the change applied ------------------------------------------------------
+  const rel = (abs) => relative(childDir, abs);
+  const rebase = (p) => (present(p) ? rel(resolve(parentDir, p)) : p);
+  const child = {
+    recipe: "0.1",
+    created: new Date().toISOString(),
+    output: { path: rel(outAbs), sha256: null },
+    factory: { ...(parent.factory ?? {}) },
+    spec: { ...parent.spec, path: rebase(parent.spec?.path) },
+    inputs: parentInputs.map((i) => ({ ...i, path: rebase(i.path) })),
+    stages: parentStages.map((s) => structuredClone(s)),
+    clicker,
+    approver: null,
+    parent: { path: rel(parentAbs), sha256: sha256(parentBytes) },
+    change: null,
+  };
+
+  let defaultChange;
+  const kind = changeKeys[0];
+  if (kind === "addInput") {
+    const { name, path, reads = [] } = change.addInput ?? {};
+    if (!present(name) || !present(path)) return usage("an added input needs a name and a path");
+    if (child.inputs.some((i) => i.name === name)) return usage(`input ${name} already exists; swap it instead`);
+    if (!Array.isArray(reads)) return usage("reads must be a list of stage ids");
+    for (const id of reads) {
+      if (!child.stages.some((s) => s.id === id)) return usage(`no stage ${id} to read input ${name}`);
+    }
+    const abs = resolve(process.cwd(), path);
+    const bytes = readBytes(abs);
+    if (!bytes) return usage(`cannot read ${path}`);
+    const hex = hold(held, bytes);
+    const order = child.inputs.reduce((m, i) => Math.max(m, i.order ?? 0), 0) + 1;
+    child.inputs.push({ name, path: rel(abs), sha256: hex, order });
+    const ref = `input:${name}`;
+    for (const id of reads) {
+      const stage = child.stages.find((s) => s.id === id);
+      // A stage with an empty reads already reads every input; making its reads explicit here
+      // would silently stop it reading everything else, so it is left as it is.
+      if (Array.isArray(stage.reads) && stage.reads.length && !stage.reads.includes(ref)) stage.reads = [...stage.reads, ref];
+    }
+    // An input no stage reads changes nothing: every stage would be reused, the child's output
+    // would be the parent's bytes, and the recipe would claim an input was used that nothing read.
+    // A regeneration must change something, so this is refused the way a no-op swap is.
+    const read = child.stages.some((s) => !Array.isArray(s.reads) || s.reads.length === 0 || s.reads.includes(ref));
+    if (!read) return usage(`no stage reads input ${name}; add --reads <stage>`);
+    defaultChange = `added input ${name} (${rel(abs)})`;
+  } else if (kind === "swapInput") {
+    const { name, path } = change.swapInput ?? {};
+    if (!present(name) || !present(path)) return usage("a swapped input needs a name and a path");
+    const input = child.inputs.find((i) => i.name === name);
+    if (!input) return usage(`no input ${name} to swap`);
+    const abs = resolve(process.cwd(), path);
+    const bytes = readBytes(abs);
+    if (!bytes) return usage(`cannot read ${path}`);
+    if (sha256(bytes) === input.sha256) return usage(`swap does not change input ${name}: ${path} has the same bytes`);
+    input.sha256 = hold(held, bytes);
+    input.path = rel(abs);
+    defaultChange = `swapped input ${name} to ${rel(abs)}`;
+  } else {
+    const version = change.factoryVersion;
+    if (!present(version)) return usage("factory version must be a non-empty string");
+    if (version === parent.factory?.version) return usage(`factory is already ${version}; that is not a change`);
+    child.factory.version = version;
+    defaultChange = `factory ${parent.factory?.version} to ${version}`;
+  }
+  child.change = present(changeText) ? changeText : defaultChange;
+
+  // Every blob the child names must be verified and reachable from the child's own store, or a
+  // reproduce of the child could not stand on its own. A blob found only in the parent's store
+  // (the child lives under a different root) is carried over, re-hashed on the way.
+  const fetch = (hex) => {
+    if (held.has(hex)) return held.get(hex);
+    for (const root of childRoot === parentRoot ? [childRoot] : [childRoot, parentRoot]) {
+      const bytes = getBlob(root, hex);
+      if (bytes !== null && sha256(bytes) === hex) {
+        if (root !== childRoot) held.set(hex, bytes);
+        return bytes;
+      }
+    }
+    return null;
+  };
+  for (const input of child.inputs) {
+    if (!present(input.sha256) || !fetch(input.sha256)) return failed(`input ${input.name}: blob missing or does not match its recorded hash`);
+  }
+  if (!fetch(child.spec.sha256)) return failed("spec: blob missing or does not match its recorded hash");
+
+  // ---- Plan and run ----------------------------------------------------------------------------
+  // Each stage is decided in order, once everything it reads is known. With a runner, an upstream
+  // rerun has already produced its real bytes by the time its readers are decided, so a reader is
+  // reused whenever its key still matches (a deterministic upstream that reproduced its parent
+  // bytes changes nothing downstream). Without a runner, a reader of a pending stage cannot be
+  // keyed, so it is pending too.
+  const plan = [];
+  const pendingIds = new Set();
+  const failedVerdicts = [];
+  for (let i = 0; i < child.stages.length; i++) {
+    const stage = child.stages[i];
+    let refs;
+    try {
+      refs = resolveReads(child, i).map(([ref]) => ref);
+    } catch (e) {
+      return failed(`stage ${stage.id}: ${e.message}`, { plan });
+    }
+    if (refs.some((ref) => ref.startsWith("stage:") && pendingIds.has(ref.slice("stage:".length)))) {
+      markPending(stage, null); // reads a stage not yet run, so its key cannot be known
+      pendingIds.add(stage.id);
+      plan.push({ id: stage.id, action: "rerun" });
+      continue;
+    }
+
+    const key = stageKey(child, i);
+    const decision = reusable(parent, i, key);
+    if (decision.reuse) {
+      if (!fetch(parentStages[i].output.sha256)) {
+        return failed(`stage ${stage.id}: recorded output blob missing or does not match its hash; cannot reuse an unverifiable stage`, { plan });
+      }
+      // The clone already carries the parent's output, verdict and (equal) key.
+      plan.push({ id: stage.id, action: "reuse" });
+      continue;
+    }
+
+    const entry = { id: stage.id, action: "rerun" };
+    if (decision.reason) entry.reason = decision.reason;
+    plan.push(entry);
+    if (!present(run)) {
+      markPending(stage, key);
+      pendingIds.add(stage.id);
+      continue;
+    }
+    const result = runStage(run, child, i, fetch);
+    if (result.error) return failed(`stage ${stage.id}: ${result.error}`, { failedStage: stage.id, plan });
+    delete stage.pending;
+    stage.output = { sha256: hold(held, result.output) };
+    stage.verdict = result.verdict;
+    stage.key = stageKey(child, i);
+    if (result.verdict.pass === false) failedVerdicts.push(stage.id);
+  }
+
+  // ---- Write -----------------------------------------------------------------------------------
+  const last = child.stages[child.stages.length - 1];
+  child.output.sha256 = last.output?.sha256 ?? null;
+  const pending = pendingIds.size > 0;
+
+  // A runner may take minutes, and anything may have appeared at out meanwhile (the runner itself
+  // included). Check again right before the first write, and refuse with nothing written.
+  if (existsSync(outAbs)) return usage(`${out} already exists; refusing to overwrite it`);
+  if (existsSync(childRecipePath)) return usage(`${childRecipePath} already exists; refusing to overwrite it`);
+
+  for (const bytes of held.values()) putBlob(childRoot, bytes);
+  if (!pending) {
+    // The child's output is the last stage's blob, written atomically and read back.
+    writeFileAtomic(outAbs, fetch(child.output.sha256));
+    if (sha256(readFileSync(outAbs)) !== child.output.sha256) {
+      try { unlinkSync(outAbs); } catch { /* nothing to remove */ }
+      return failed(`${out} does not hash to the child's output.sha256`, { plan });
+    }
+  }
+  writeRecipe(childRecipePath, child);
+  return { ok: true, childRecipe: childRecipePath, output: pending ? null : outAbs, plan, pending, failedVerdicts };
+}
+
+// Reuse is proven twice over: the key recomputed from the child's hashes equals the key the parent
+// recorded, AND the parent's recorded key equals the key recomputed from the parent's own recorded
+// hashes. Without the second check, a parent key edited to match the child would pass an old
+// output off as made under conditions it never was, and a reproduce of the child could not tell.
+function reusable(parent, index, childKey) {
+  const ps = parent.stages[index];
+  if (!ps || ps.pending === true || !present(ps.output?.sha256) || !present(ps.key)) return { reuse: false };
+  let selfKey;
+  try { selfKey = stageKey(parent, index); } catch { selfKey = null; }
+  if (selfKey !== ps.key) return { reuse: false, reason: "parent key does not match its record" };
+  return { reuse: childKey === ps.key };
+}
+
+function markPending(stage, key) {
+  stage.key = key;
+  stage.output = null;
+  stage.verdict = null;
+  stage.pending = true;
+}
+
+// Runs one stage through the caller's runner. The runner gets, on stdin, the stage id, its
+// resolved reads (each materialized from its blob into a temp file) and its model; its stdout,
+// byte for byte, is the stage's output. A final `VERDICT {...}` line on stderr is the verdict.
+// A runner that reports no verdict gets a failing one: silence is not a verdict, and a recipe
+// must never claim a station checked something that nothing checked.
+function runStage(run, recipe, index, fetch) {
+  const stage = recipe.stages[index];
+  const tmp = mkdtempSync(join(tmpdir(), "hyperspec-run-"));
+  try {
+    const reads = resolveReads(recipe, index).map(([ref, hex], n) => {
+      const bytes = fetch(hex);
+      if (!bytes) throw new Error(`read ${ref}: blob ${hex} missing`);
+      const path = join(tmp, `${n}-${ref.replace(/[^A-Za-z0-9._-]/g, "_")}`);
+      writeFileSync(path, bytes);
+      return { ref, sha256: hex, path };
+    });
+    const job = { stage: stage.id, reads, model: stage.model ?? null };
+    const res = spawnSync("/bin/sh", ["-c", run], { input: JSON.stringify(job), maxBuffer: RUNNER_MAX_BUFFER });
+    const stderr = res.stderr ? res.stderr.toString("utf8") : "";
+    if (res.error) return { error: `runner could not run: ${res.error.message}` };
+    if (res.status !== 0) {
+      const how = res.signal ? `was killed by ${res.signal}` : `exited ${res.status}`;
+      const tail = stderr.trim().split("\n").slice(-5).join("\n");
+      return { error: `runner ${how}${tail ? `: ${tail}` : ""}` };
+    }
+    const verdict = parseVerdict(stderr);
+    if (verdict.error) return { error: verdict.error };
+    return { output: res.stdout, verdict: verdict.value };
+  } catch (e) {
+    return { error: e.message };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function parseVerdict(stderr) {
+  const lines = stderr.split(/\r?\n/).filter((l) => l.startsWith("VERDICT "));
+  if (!lines.length) return { value: { station: "runner", pass: false, note: "runner reported no verdict" } };
+  const text = lines[lines.length - 1].slice("VERDICT ".length).trim();
+  let value;
+  try { value = JSON.parse(text); } catch (e) { return { error: `invalid VERDICT line from the runner: ${e.message}` }; }
+  if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.pass !== "boolean") {
+    return { error: "invalid VERDICT line from the runner: it must be an object with a boolean pass" };
+  }
+  return { value: { station: "runner", note: "", ...value } };
+}
+
+function hold(held, bytes) {
+  const hex = sha256(bytes);
+  if (!held.has(hex)) held.set(hex, bytes);
+  return hex;
+}
+
+function readBytes(abs) {
+  try { return readFileSync(abs); } catch { return null; }
+}
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}

package/src/reproduce.mjs

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { sha256 } from "./hash.mjs";
+import { getBlob, isSha256, storeRoot, verifyBlob } from "./blobs.mjs";
+import { insideDir, writeFileAtomic } from "./fsutil.mjs";
+import { readRecipe, stageKey } from "./recipe.mjs";
+
+const present = (v) => typeof v === "string" && v.trim().length > 0;
+const MALFORMED = "recorded hash is not a SHA-256 hash (64 lowercase hex characters)";
+// A recorded hash that is not well formed names no blob at all; say so rather than "missing".
+const blobWhy = (hex, why) => (present(hex) && !isSha256(hex) ? MALFORMED : why);
+
+// Spec requirement `reproduce`: replay the record and hash-check it. Never invokes a model,
+// never runs a command, never regenerates a byte of content — every blob this looks at already
+// exists in the store, and this only confirms the recipe's own claims about it still hold.
+//
+// Checks, in order (and every one is reported, nothing stops the walk early): every input blob
+// verifies; the spec blob verifies; for each stage, its output blob verifies AND its recorded
+// key equals the recomputed key; the output blob equals output.sha256; the output file on disk,
+// if present, hashes to output.sha256.
+export function reproduce(recipePath, { store, restore = false } = {}) {
+  const loaded = readRecipe(recipePath);
+  if (loaded.error) return { ok: false, error: loaded.error, steps: [], firstMismatch: null };
+  const { data: recipe, dir } = loaded;
+  const root = storeRoot({ from: dir, store });
+
+  const steps = [];
+  // Every step's ok/why is decided through setStep, including its own creation (addStep). One
+  // path for every mutation, so a step is never left with a stale why after a later change.
+  function setStep(step, ok, why) {
+    step.ok = ok;
+    if (ok || !why) delete step.why;
+    else step.why = why;
+  }
+  function addStep(ref, sha256Value, ok, why) {
+    const step = { ref, sha256: sha256Value ?? null, ok: true };
+    steps.push(step);
+    setStep(step, ok, why);
+    return step;
+  }
+
+  // 1. Every input blob verifies.
+  const inputs = Array.isArray(recipe.inputs) ? recipe.inputs : [];
+  for (const input of inputs) {
+    const hex = input?.sha256;
+    const ok = present(hex) && verifyBlob(root, hex);
+    addStep(`input:${input?.name}`, hex, ok, blobWhy(hex, "input blob missing or does not match its recorded hash"));
+  }
+
+  // 2. The spec blob verifies.
+  {
+    const hex = recipe.spec?.sha256;
+    const ok = present(hex) && verifyBlob(root, hex);
+    addStep("spec", hex, ok, blobWhy(hex, "spec blob missing or does not match its recorded hash"));
+  }
+
+  // 3. For each stage: its output blob verifies, and its recorded key equals the recomputed key.
+  const stages = Array.isArray(recipe.stages) ? recipe.stages : [];
+  stages.forEach((stage, index) => {
+    const id = stage?.id ?? `#${index}`;
+    const pending = stage?.pending === true || stage?.output == null || !present(stage.output?.sha256);
+    if (pending) {
+      addStep(`stage:${id}`, stage?.output?.sha256, false, "stage is pending");
+    } else {
+      const hex = stage.output.sha256;
+      const ok = verifyBlob(root, hex);
+      addStep(`stage:${id}`, hex, ok, blobWhy(hex, "stage output blob missing or does not match its recorded hash"));
+    }
+
+    let keyOk = false;
+    let keyWhy = "stage key could not be recomputed";
+    try {
+      const recomputed = stageKey(recipe, index);
+      keyOk = present(stage?.key) && stage.key === recomputed;
+      if (!keyOk) keyWhy = "recorded key does not match the recomputed key";
+    } catch (e) {
+      keyWhy = `stage key could not be recomputed: ${e.message}`;
+    }
+    addStep(`stage:${id}#key`, stage?.key, keyOk, keyWhy);
+  });
+
+  // 4. The output blob equals output.sha256.
+  const outputSha = recipe.output?.sha256;
+  const lastStage = stages[stages.length - 1];
+  let outputBlobOk = false;
+  let outputBlobWhy = "output.sha256 is missing";
+  if (present(outputSha)) {
+    if (!lastStage || lastStage.output?.sha256 !== outputSha) {
+      outputBlobWhy = "output.sha256 does not match the last stage's output";
+    } else if (!verifyBlob(root, outputSha)) {
+      outputBlobWhy = blobWhy(outputSha, "output blob missing or does not match output.sha256");
+    } else {
+      outputBlobOk = true;
+    }
+  }
+  addStep("output:blob", outputSha, outputBlobOk, outputBlobWhy);
+
+  // 5. The output file on disk, if present, hashes to output.sha256. Absent is vacuously fine:
+  // reproduce doesn't require the file to already exist, only that it agrees when it does.
+  //
+  // The recipe is a plain JSON file on disk — exactly the kind of claim reproduce exists to
+  // distrust — so output.path is never trusted blind. A hand-edited or corrupted recipe could
+  // name a path outside the recipe's own directory (a `../` climb, or an absolute path); refuse
+  // before touching disk at all, rather than reading from or (worse, under --restore) writing to
+  // wherever it points.
+  const outputPath = recipe.output?.path;
+  let restored = false;
+  if (present(outputPath) && !insideDir(dir, outputPath)) {
+    addStep("output:file", outputSha, false, "output path escapes the recipe directory");
+  } else {
+    const outputAbs = present(outputPath) ? resolve(dir, outputPath) : null;
+    const fileStep = addStep("output:file", outputSha, true);
+    if (outputAbs) {
+      const fileExists = existsSync(outputAbs);
+      let matches = true;
+      if (fileExists) {
+        const bytes = readFileSync(outputAbs);
+        matches = present(outputSha) && sha256(bytes) === outputSha;
+        if (!matches) setStep(fileStep, false, "output file does not match output.sha256");
+      }
+
+      // restore: true writes the output file from its blob, but only when the output blob
+      // itself verified (step 4) — restoring from an unverified blob would just write
+      // different wrong bytes. Covers both a lost file (never existed / deleted) and an
+      // edited one. The write is atomic (temp file + rename, same pattern as putBlob), so a
+      // crash mid-write never leaves the file in a state that is neither the old nor the new
+      // content, and a write failure is caught and reported as a failing step rather than
+      // thrown out of reproduce() — this function always returns a structured result.
+      const needsRestore = !fileExists || !matches;
+      if (restore && needsRestore && outputBlobOk) {
+        const blob = getBlob(root, outputSha);
+        if (blob !== null) {
+          try {
+            writeFileAtomic(outputAbs, blob);
+            restored = true;
+            // Re-evaluate for real: read back what actually landed on disk and hash it, rather
+            // than assuming the write did what it intended.
+            const writtenBytes = readFileSync(outputAbs);
+            const writtenOk = present(outputSha) && sha256(writtenBytes) === outputSha;
+            setStep(fileStep, writtenOk, "restored output file does not match output.sha256");
+          } catch (e) {
+            setStep(fileStep, false, `failed to restore the output file: ${e.message}`);
+          }
+        }
+      }
+    }
+  }
+
+  const firstFail = steps.find((s) => !s.ok);
+  return {
+    ok: steps.every((s) => s.ok),
+    steps,
+    firstMismatch: firstFail ? firstFail.ref : null,
+    restored,
+  };
+}

package/src/rules.mjs

@@ -1,5 +1,7 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
+import { lintProfile } from "./profiles.mjs";
+import { str } from "./placeholder.mjs";
 
 export const TESTS = Object.freeze([
   { n: 1, name: "every decision is accounted for" },
@@ -25,22 +27,36 @@ const FENCE = /^ {0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:^ {0,3}\1[`~]*[ \t]*$|(?![
 const INLINE_CODE = /(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g;
 const prose = (body) => String(body || "").replace(FENCE, "").replace(INLINE_CODE, "");
 const list = (v) => (Array.isArray(v) ? v : []);
-// A value that is only null or ~ is a placeholder: the reader (@supersuit/superskill/yaml) keeps
-// these as the literal strings "null" and "~" rather than resolving them to YAML's own null, so
-// they must never count as present. A value that is only a YAML comment (source: # TODO) is
-// handled upstream since superskill 0.2.1: the reader returns "" for it, same as any other blank
-// scalar, so it already fails str()'s own emptiness check and needs no rule here. A QUOTED value
-// that happens to start with "#" (source: "# literal") is real text and must count as present.
-// Every presence check goes through str().
-const PLACEHOLDER = /^(null|~)$/is;
-const str = (v) => { const t = typeof v === "string" ? v.trim() : ""; return PLACEHOLDER.test(t) ? "" : t; };
+// str() (a value that is null/~/todo/tbd/fixme/xxx/placeholder never counts as present) is
+// shared, from src/placeholder.mjs: writing.mjs and writing-fields.mjs import the same function,
+// so a placeholder word closes every presence check in the linter at once. A value that is only a
+// YAML comment (source: # TODO) is handled upstream since superskill 0.2.1: the reader returns ""
+// for it, same as any other blank scalar, so it already fails str()'s own emptiness check and
+// needs no rule here. A QUOTED value that happens to start with "#" (source: "# literal") is real
+// text and must count as present.
 const f = (test, id, severity, message, fix) => ({ test, id, severity, message, fix });
+// The versions of the format this linter knows. A spec naming any other may follow rules it
+// cannot check, so it is warned about rather than failed.
+export const KNOWN_VERSIONS = Object.freeze(["0.1"]);
+// "file", "other" (a directory or a device), or null when nothing is there.
+const kind = (p) => { try { return statSync(p).isFile() ? "file" : "other"; } catch { return null; } };
+const UNIQUE_IDS = "Ids must be unique across decisions and requirements; rename one.";
 
-export function lintSpec(spec, { exists = existsSync } = {}) {
+export function lintSpec(spec) {
   const d = spec.data || {};
   const out = [];
   const here = (p) => resolve(spec.dir || ".", p);
 
+  // The format version. Not one of the nine tests: a stranger resuming the spec (test 7) needs to
+  // know which standard it was written against, so an unknown one is a warning there.
+  const version = str(d.hyperspec);
+  if (!KNOWN_VERSIONS.includes(version)) out.push(f(7, "hyperspec-version", "warn", `hyperspec version "${version}" is not one this linter knows (${KNOWN_VERSIONS.join(", ")})`, "Set hyperspec: to a version this linter knows, or upgrade @supersuit/hyperspec."));
+
+  // A spec with no profile: runs no profile rules at all, so it lints exactly as it always has.
+  // One declared runs that profile's own rules (writing.mjs for profile: writing), every finding
+  // still reported under one of the nine tests below; an unknown profile name is a warning here.
+  out.push(...lintProfile(spec));
+
   // 1 and 4, decisions
   const decisions = list(d.decisions);
   if (!decisions.length) out.push(f(1, "decisions", "fail", "no decisions are listed", "List every decision this kind of work has under decisions:, each decided, delegated or open."));
@@ -48,7 +64,7 @@ export function lintSpec(spec, { exists = existsSync } = {}) {
   decisions.forEach((x, i) => {
     const id = str(x?.id) || `#${i + 1}`;
     if (!str(x?.id)) out.push(f(1, "decision-id", "fail", `decision ${id} has no id`, "Give it a short id."));
-    else if (seen.has(id)) out.push(f(1, "decision-id", "fail", `decision id "${id}" is used twice`, "Make every id unique."));
+    else if (seen.has(id)) out.push(f(1, "decision-id", "fail", `decision id "${id}" is used twice`, UNIQUE_IDS));
     seen.add(id);
     const st = str(x?.state);
     if (!["decided", "delegated", "open"].includes(st)) out.push(f(1, "decision-state", "fail", `decision "${id}" has state "${st || "(none)"}"`, "Set state to decided, delegated or open."));
@@ -63,8 +79,17 @@ export function lintSpec(spec, { exists = existsSync } = {}) {
   // 2, 3 and 4, requirements
   const reqs = list(d.requirements);
   if (!reqs.length) out.push(f(2, "requirements", "fail", "no requirements are listed", "List what the finished work must meet under requirements:."));
+  // One id namespace across decisions and requirements: a recipe maps every id to its author, so
+  // a shared id would silently lose one of them. Reported under test 1.
+  const decisionIds = new Set(decisions.map((x) => str(x?.id)).filter(Boolean));
+  const reqSeen = new Set();
   reqs.forEach((r, i) => {
     const id = str(r?.id) || `#${i + 1}`;
+    if (str(r?.id)) {
+      if (reqSeen.has(id)) out.push(f(1, "requirement-id", "fail", `requirement id "${id}" is used twice`, UNIQUE_IDS));
+      else if (decisionIds.has(id)) out.push(f(1, "requirement-id", "fail", `id "${id}" is used by a decision and a requirement`, UNIQUE_IDS));
+      reqSeen.add(id);
+    }
     if (!str(r?.text)) out.push(f(2, "requirement-text", "fail", `requirement "${id}" has no text`, "Write the requirement."));
     const fw = str(r?.fails_when);
     if (!fw) out.push(f(2, "fails-when", "fail", `requirement "${id}" does not say what would show it failed`, "Add fails_when: something a person or a check could observe."));
@@ -89,15 +114,27 @@ export function lintSpec(spec, { exists = existsSync } = {}) {
   ex.forEach((e, i) => {
     const p = str(e?.path);
     if (!p) out.push(f(6, "example-path", "fail", `example ${i + 1} has no path`, "Add path: to the example."));
-    else if (!/^https?:\/\//.test(p) && !exists(here(p))) out.push(f(6, "example-missing", "fail", `example "${p}" does not exist`, "Fix the path, or add the example file."));
+    else if (!/^https?:\/\//.test(p)) {
+      const k = kind(here(p));
+      if (!k) out.push(f(6, "example-missing", "fail", `example "${p}" does not exist`, "Fix the path, or add the example file."));
+      else if (k !== "file") out.push(f(6, "example-not-file", "fail", `example "${p}" is not a file`, "Point path: at one example file, not a folder."));
+      else if (spec.path && here(p) === resolve(spec.path)) out.push(f(6, "example-self", "fail", `example "${p}" is this spec itself`, "Point at a real example of the work, not the spec that describes it."));
+    }
     if (!str(e?.why)) out.push(f(6, "example-why", "fail", `example ${p || i + 1} does not say why it is an example`, "Add why: what it shows that an adjective could not."));
   });
 
   // 7
-  const next = str(d.resume?.next_action);
-  if (!next) out.push(f(7, "next-action", "fail", "no resume.next_action", "Write the single concrete step that starts the next session."));
-  else if (NO_ACTION.test(next)) out.push(f(7, "next-action-vague", "fail", `next action "${next}" names no action`, "Name the concrete step."));
-  else if (CONVERSATION.test(next)) out.push(f(7, "next-action-vague", "fail", `next action "${next}" points into a conversation the next reader cannot see`, "State the step itself."));
+  // NO_ACTION is checked against the RAW trimmed value, ahead of str()'s placeholder-blanking:
+  // two of its own words (tbd, todo) are now also placeholder words str() treats as blank, and
+  // "next action names no action" is the more specific, more correct message for those than "no
+  // resume.next_action" would be (something WAS written; it just names no action).
+  const rawNext = typeof d.resume?.next_action === "string" ? d.resume.next_action.trim() : "";
+  if (rawNext && NO_ACTION.test(rawNext)) out.push(f(7, "next-action-vague", "fail", `next action "${rawNext}" names no action`, "Name the concrete step."));
+  else {
+    const next = str(d.resume?.next_action);
+    if (!next) out.push(f(7, "next-action", "fail", "no resume.next_action", "Write the single concrete step that starts the next session."));
+    else if (CONVERSATION.test(next)) out.push(f(7, "next-action-vague", "fail", `next action "${next}" points into a conversation the next reader cannot see`, "State the step itself."));
+  }
   if (CONVERSATION.test(prose(spec.body))) out.push(f(7, "conversation-pointer", "warn", "the body points into a conversation the next reader cannot see", "State the thing itself."));
 
   // 8
@@ -108,11 +145,13 @@ export function lintSpec(spec, { exists = existsSync } = {}) {
   const led = str(d.improvement?.ledger);
   if (!led) out.push(f(9, "ledger", "fail", "no improvement.ledger", "Name the file each run writes its verdict to."));
   else {
-    // A declared ledger not yet written is fine. One that exists must be a readable file.
+    // A declared ledger not yet written is a warning: the first run may create it. One that
+    // exists must be a readable file.
     let st = null;
     try { st = statSync(here(led)); } catch { /* not written yet */ }
     let text = null;
-    if (st && !st.isFile()) out.push(f(9, "ledger-not-file", "fail", `ledger path ${led} is not a file`, "Point improvement.ledger at a file, one JSON object per line."));
+    if (!st) out.push(f(9, "ledger-missing", "warn", `ledger ${led} does not exist yet`, "Create it as an empty file, so the first run has somewhere to write its verdict."));
+    else if (!st.isFile()) out.push(f(9, "ledger-not-file", "fail", `ledger path ${led} is not a file`, "Point improvement.ledger at a file, one JSON object per line."));
     else if (st) {
       try { text = readFileSync(here(led), "utf8"); } catch (e) { out.push(f(9, "ledger-unreadable", "fail", `ledger ${led} cannot be read (${e.code || e.message})`, "Make the ledger file readable.")); }
     }

package/src/score.mjs

@@ -1,4 +1,5 @@
 import { TESTS } from "./rules.mjs";
+import { profileStatus } from "./profiles.mjs";
 
 export function score(findings, data = {}) {
   const failed = new Set(findings.filter((x) => x.severity === "fail").map((x) => x.test));
@@ -6,7 +7,12 @@ export function score(findings, data = {}) {
   const open = (Array.isArray(data.decisions) ? data.decisions : [])
     .filter((x) => String(x?.state || "").trim() === "open").map((x) => String(x.id || "").trim());
   const status = failed.size ? "fail" : open.length ? "blocked" : "pass";
-  return { tests, passed: tests.filter((t) => t.pass).length, open, status };
+  const out = { tests, passed: tests.filter((t) => t.pass).length, open, status };
+  // Only when a known profile ran: profileStatus returns undefined for no profile: at all, and
+  // for one this linter does not know (nothing to count when its rules were never checked).
+  const profile = profileStatus(data, findings);
+  if (profile) out.profile = profile;
+  return out;
 }
 
 export const exitCode = (status) => ({ pass: 0, fail: 1, blocked: 3 })[status] ?? 2;