@supersuit/superskill 0.4.0 → 0.6.0

package/src/goldens.mjs

@@ -1,38 +1,97 @@
-// goldens/<id>/: input.md, the approved output (output.md, or any other non-input file),
-// and APPROVAL.json written by a person: { approvals: [{approved_by, approved_at, skill_sha,
-// rationale, basis, evidence}] }, or the single-approval shape from before 0.3.0.
+// goldens/<id>/: input.md, expectations.json (0.6.0: the checklist a right answer meets,
+// graded by --run), the reference output (output.md, or any other non-input file),
+// APPROVAL.json written by a person: { approvals: [{approved_by, approved_at, skill_sha,
+// rationale, basis, evidence}] } (or the single-approval shape from before 0.3.0),
+// PROVENANCE.json saying where the example came from (0.5.0), and, for an anonymized twin of a
+// private golden, ANONYMIZED.json, the anonymizer's receipt.
+//
+// A golden may also live OUTSIDE the skill, in a private folder the operator keeps
+// (<private>/<skill-name>/<id>/), because a real run's input and output are usually about real
+// people and should not travel with a skill that is shared. The doctor reads both.
 import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 
-export function readGoldens(dir) {
-  const root = join(dir, "goldens");
-  if (!existsSync(root)) return [];
+/** Files in a golden folder that describe it rather than being its input or output. */
+export const META_FILES = new Set(["APPROVAL.json", "PROVENANCE.json", "ANONYMIZED.json", "expectations.json"]);
+
+/** Where goldens are read from: the skill's own goldens/, then the private folder for its name. */
+export function goldenRoots(dir, { privateGoldens = null, name = null } = {}) {
+  const roots = [{ root: join(dir, "goldens"), private: false }];
+  if (privateGoldens && name) roots.push({ root: join(privateGoldens, name), private: true });
+  return roots;
+}
+
+const readJsonFile = (p) => {
+  if (!existsSync(p)) return { value: null, error: null };
+  try { return { value: JSON.parse(readFileSync(p, "utf8")), error: null }; }
+  catch (e) { return { value: null, error: e.message }; }
+};
+
+export function readGoldens(dir, opts = {}) {
   const out = [];
-  for (const id of readdirSync(root).sort()) {
-    const gdir = join(root, id);
-    try { if (!statSync(gdir).isDirectory()) continue; } catch { continue; }
-    const files = readdirSync(gdir);
-    const inputName = files.find((f) => /^input\./i.test(f));
-    const outputName = files.find((f) => /^output\./i.test(f)) || files.find((f) => f !== inputName && f !== "APPROVAL.json" && !f.startsWith("."));
-    let approval = null, approvalError = null;
-    if (files.includes("APPROVAL.json")) {
-      try { approval = JSON.parse(readFileSync(join(gdir, "APPROVAL.json"), "utf8")); }
-      catch (e) { approvalError = e.message; }
+  for (const { root, private: priv } of goldenRoots(dir, opts)) {
+    if (!existsSync(root)) continue;
+    for (const id of readdirSync(root).sort()) {
+      const gdir = join(root, id);
+      try { if (!statSync(gdir).isDirectory()) continue; } catch { continue; }
+      const files = readdirSync(gdir).filter((f) => { try { return statSync(join(gdir, f)).isFile(); } catch { return false; } });
+      const inputName = files.find((f) => /^input\./i.test(f));
+      const outputName = files.find((f) => /^output\./i.test(f)) || files.find((f) => f !== inputName && !META_FILES.has(f) && !f.startsWith("."));
+      const appr = readJsonFile(join(gdir, "APPROVAL.json"));
+      const prov = readJsonFile(join(gdir, "PROVENANCE.json"));
+      const anon = readJsonFile(join(gdir, "ANONYMIZED.json"));
+      const provenance = prov.value;
+      const exp = readJsonFile(join(gdir, "expectations.json"));
+      const expList = Array.isArray(exp.value) ? exp.value : Array.isArray(exp.value?.expectations) ? exp.value.expectations : [];
+      out.push({
+        id,
+        dir: gdir,
+        private: priv,
+        input: inputName ? readFileSync(join(gdir, inputName), "utf8") : null,
+        outputFile: outputName || null,
+        output: outputName ? readFileSync(join(gdir, outputName), "utf8") : null,
+        approval: appr.value,
+        approvals: approvalsOf(appr.value),
+        approvalError: appr.error,
+        provenance,
+        provenanceError: prov.error,
+        anonymized: anon.value,
+        origin: originOf(provenance, anon.value),
+        // 0.6.0: what a right answer does, graded by --run. output.md is the reference that
+        // proves the task is solvable; it is no longer what the output has to look like.
+        expectations: expList.filter((x) => typeof x === "string" && x.trim()),
+        expectationsError: exp.error,
+      });
     }
-    out.push({
-      id,
-      dir: gdir,
-      input: inputName ? readFileSync(join(gdir, inputName), "utf8") : null,
-      outputFile: outputName || null,
-      output: outputName ? readFileSync(join(gdir, outputName), "utf8") : null,
-      approval,
-      approvals: approvalsOf(approval),
-      approvalError,
-    });
   }
   return out;
 }
 
+/** Where a golden's example came from. `real-run` is the only source that can reach superskill. */
+export const SOURCES = ["real-run", "synthetic", "synthetic-reconstruction"];
+
+/**
+ * Is this golden a real run a person accepted, and if not, why not?
+ *
+ * A real run names the run it came from (a session, a commit, a ledger id, or, for an
+ * anonymized twin, `derived_from`: a hash of the private original, never its content) and the
+ * person who accepted the output when it happened, and when. An anonymized twin must also carry
+ * the anonymizer's receipt, because "the original was accepted" and "this twin still says the
+ * same thing" are different claims.
+ */
+export function originOf(prov, receipt = null) {
+  if (!prov || typeof prov !== "object") return { real: false, why: "no PROVENANCE.json" };
+  if (prov.source !== "real-run") return { real: false, why: `source is ${JSON.stringify(prov.source ?? null)}, not "real-run"` };
+  const run = prov.run && typeof prov.run === "object" ? prov.run : {};
+  const ref = ["session", "commit", "ledger_id"].map((k) => run[k]).concat(prov.derived_from).find((x) => typeof x === "string" && x.trim());
+  if (!ref) return { real: false, why: "names no run (run.session, run.commit, run.ledger_id or derived_from)" };
+  const acc = prov.accepted && typeof prov.accepted === "object" ? prov.accepted : {};
+  if (!(typeof acc.by === "string" && acc.by.trim())) return { real: false, why: "names no person who accepted the run (accepted.by)" };
+  if (!validDate(acc.at)) return { real: false, why: "has no valid accepted.at" };
+  if (prov.anonymized === true && !(receipt && typeof receipt === "object" && receipt.fingerprint)) return { real: false, why: "is an anonymized twin with no ANONYMIZED.json receipt" };
+  return { real: true, why: "" };
+}
+
 /** What an approval rests on. `judgment`: the people who approved it read it and said it is right.
  *  `outcome`: it produced a result in the world someone can check (a client landed, a call booked).
  *  Being liked and being proven are different weights, and a golden says which it carries. */
@@ -82,3 +141,12 @@ export function withApproval(existing, entry) {
 }
 
 export const isApproved = (g) => approvalsOf(g.approval).length > 0;
+
+/** Approved AND from a real run a person accepted: the only golden that counts for superskill. */
+export const isRealApproved = (g) => isApproved(g) && (g.origin || originOf(g.provenance, g.anonymized)).real;
+
+/** The options readGoldens needs for a loaded skill: its name and the private folder, if any. */
+export const goldenOpts = (ctx, opts = {}) => ({
+  name: (typeof ctx.data?.name === "string" && ctx.data.name) || ctx.folderName,
+  privateGoldens: opts.privateGoldens ?? ctx.privateGoldens ?? process.env.SUPERSKILL_PRIVATE_GOLDENS ?? null,
+});

package/src/ledger.mjs

@@ -12,7 +12,10 @@ export function ledgerPaths(skillDir, skillName) {
   const out = [];
   const local = join(skillDir, "invocations.jsonl");
   if (existsSync(local)) out.push(local);
-  const root = join(homedir(), ".freedom", "ledger", "skills");
+  // FREEDOM_SKILL_LEDGER_HOME is where Freedom itself writes when it is re-pointed (tests, a
+  // second profile); read the same place it writes.
+  const home = process.env.FREEDOM_SKILL_LEDGER_HOME || join(homedir(), ".freedom", "ledger");
+  const root = join(home, "skills");
   if (existsSync(root) && skillName) {
     for (const plugin of readdirSync(root).sort()) {
       const p = join(root, plugin, `${skillName}.jsonl`);
@@ -30,15 +33,48 @@ export function ledgerMisses(path, known, skillName) {
     let rec;
     try { rec = JSON.parse(line); } catch { continue; }
     if (!rec || !rec.id || known.has(rec.id)) continue;
-    if (skillName && rec.skill && rec.skill !== skillName) continue;
+    // A sandbox run (superskill doctor --run) is a test of the skill, not a use of it.
+    if (rec.synthetic) continue;
+    if (skillName && rec.skill && bare(rec.skill) !== bare(skillName)) continue;
     const kinds = (Array.isArray(rec.interventions) ? rec.interventions : []).filter((i) => i && MISS_KINDS.has(i.kind));
     const failed = rec.outcome === "failed";
     if (!kinds.length && !failed) continue;
     const parts = kinds.map((i) => `${i.kind}${i.note || i.what ? `: ${i.note || i.what}` : ""}`);
-    if (failed) parts.unshift(`run failed${Array.isArray(rec.errors) && rec.errors.length ? ` (${rec.errors.slice(0, 2).join("; ")})` : ""}`);
+    if (failed) parts.unshift(`run failed${Array.isArray(rec.errors) && rec.errors.length ? ` (${rec.errors.slice(0, 2).map((e) => (typeof e === "string" ? e : e?.kind || "error")).join("; ")})` : ""}`);
     const date = typeof rec.started === "string" && /^\d{4}-\d{2}-\d{2}/.test(rec.started) ? rec.started.slice(0, 10) : null;
-    out.push({ date, status: "open", what: parts.join("; ").replace(/\s+/g, " ").slice(0, 300), expected: "", source: `freedom-ledger ${rec.id}` });
+    // A correction made in the operator's NEXT message is the best "should have" there is, and the
+    // ledger keeps only where it is, never its words: point at it, so the fixer reads it there.
+    const ref = rec.next_turn_ref && rec.session_id ? ` (the correction is the operator's message in session ${String(rec.session_id).slice(0, 8)} at ${rec.next_turn_ref.at || "?"}${Number.isFinite(rec.next_turn_ref.offset) ? `, transcript byte ${rec.next_turn_ref.offset}` : ""})` : "";
+    const expected = rec.corrected_after ? `what the operator asked for instead${ref}` : "";
+    out.push({ date, status: "open", what: parts.join("; ").replace(/\s+/g, " ").slice(0, 300), expected, source: `freedom-ledger ${rec.id}` });
     known.add(rec.id);
   }
   return out;
 }
+
+const bare = (name) => String(name || "").split(":").pop();
+
+/**
+ * How many runs the person accepted, from Freedom's `next_turn` verdict (the class of the first
+ * message after a run handed back). Runs with no verdict are left out of both sides, so a missing
+ * record can never read as an acceptance, and sandbox runs never count.
+ */
+export function acceptedRate(paths, { now = new Date(), days = 30 } = {}) {
+  const since = now.getTime() - days * 86400000;
+  let judged = 0, accepted = 0, synthetic = 0;
+  for (const p of paths) {
+    let text = "";
+    try { text = readFileSync(p, "utf8"); } catch { continue; }
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      let rec; try { rec = JSON.parse(line); } catch { continue; }
+      const t = Date.parse(rec?.started || "");
+      if (!Number.isFinite(t) || t < since || t > now.getTime()) continue;
+      if (rec.synthetic) { synthetic++; continue; }
+      if (!rec.next_turn || rec.next_turn === "none") continue;
+      judged++;
+      if (["close", "go", "new_topic"].includes(rec.next_turn) && !rec.corrected_after && !["failed", "abandoned"].includes(rec.outcome)) accepted++;
+    }
+  }
+  return { judged, accepted, synthetic };
+}

package/src/misses.mjs

@@ -1,41 +1,49 @@
-// MISSES.md: one dated entry per time the skill got something wrong.
+// MISSES.md: one dated entry per time the skill got something wrong. It is also where a
+// skill's history lives (0.6.0): the story of the incident that earned a rule goes here, and
+// SKILL.md keeps only the rule and a one-line why.
 //
 //   ## m1 · 2026-09-20 · fixed
-//   - What happened: ...
+//   - What happened: ...                (an indented line under a field continues it)
 //   - Should have: ...
-//   - Fix: <commit sha or note>
+//   - Fix: <commit sha or note: the rule now in SKILL.md>
 //   - Eval: m1
+//   - Quote: "what the person said"     (optional)
 //   - Source: freedom-ledger <id>      (optional)
 import { readFileSync, existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 export const MISSES_HEADER = `# Misses
 
-Every time this skill got something wrong. An open miss older than 14 days blocks the
-superskill level; a fixed miss must name the eval that would catch it again.
+Every time this skill got something wrong, and the story behind each rule it learned. An open
+miss blocks the superskill level; a fixed miss must name the eval that would catch it again.
 Written by \`superskill miss\` and \`superskill fix\`, and readable by hand.
 `;
 
 const HEAD_RE = /^##\s+(m\d+)\s*[·|\-–]\s*(\d{4}-\d{2}-\d{2})\s*[·|\-–]\s*(open|fixed)\s*$/i;
-const FIELDS = { "what happened": "what", "should have": "expected", fix: "fix", eval: "eval", source: "source" };
+const FIELDS = { "what happened": "what", "should have": "expected", fix: "fix", eval: "eval", quote: "quote", source: "source" };
 
 export function parseMisses(text) {
   const out = [];
   let cur = null;
+  let last = null;
   const lines = String(text).replace(/\r\n?/g, "\n").split("\n");
   lines.forEach((line, i) => {
     const h = line.match(HEAD_RE);
     if (h) {
-      cur = { id: h[1].toLowerCase(), date: h[2], status: h[3].toLowerCase(), what: "", expected: "", fix: "", eval: "", source: "", line: i + 1 };
+      cur = { id: h[1].toLowerCase(), date: h[2], status: h[3].toLowerCase(), what: "", expected: "", fix: "", eval: "", quote: "", source: "", line: i + 1 };
+      last = null;
       out.push(cur);
       return;
     }
-    if (/^##\s/.test(line)) { cur = null; return; }
-    const f = cur && line.match(/^\s*[-*]\s*([A-Za-z ]+?)\s*:\s*(.*)$/);
-    if (f) {
-      const key = FIELDS[f[1].toLowerCase()];
-      if (key) cur[key] = f[2].trim();
-    }
+    if (/^##\s/.test(line)) { cur = null; last = null; return; }
+    if (!cur) return;
+    const f = line.match(/^\s*[-*]\s*([A-Za-z ]+?)\s*:\s*(.*)$/);
+    const key = f && FIELDS[f[1].toLowerCase()];
+    if (key) { cur[key] = f[2].trim(); last = key; return; }
+    // A story rarely fits on one line: an indented line continues the field above it.
+    if (last && /^\s{2,}\S/.test(line)) { cur[last] = `${cur[last]} ${line.trim()}`.trim(); return; }
+    if (!line.trim()) return;
+    last = null;
   });
   return out;
 }
@@ -50,6 +58,7 @@ export function formatMiss(m) {
   const lines = [`## ${m.id} · ${m.date} · ${m.status}`, `- What happened: ${m.what}`];
   if (m.expected) lines.push(`- Should have: ${m.expected}`);
   lines.push(`- Fix: ${m.fix || ""}`, `- Eval: ${m.eval || ""}`);
+  if (m.quote) lines.push(`- Quote: ${m.quote}`);
   if (m.source) lines.push(`- Source: ${m.source}`);
   return lines.join("\n") + "\n";
 }

package/src/realruns.mjs

@@ -0,0 +1,122 @@
+// The real-run record (0.6.0): how often the skill did the job for a real person with no
+// correction, counted separately for every model and harness it ran on.
+//
+// Harness-neutral on purpose. Any harness, ledger or script can write the file; the doctor only
+// reads it. Format `superskill-real-runs/1`:
+//
+//   {
+//     "format": "superskill-real-runs/1",
+//     "skill": "weekly-status",
+//     "generated_at": "2026-10-06T12:00:00Z",
+//     "source": "freedom-skill-ledger",
+//     "pairs": [
+//       { "model": "claude-opus-5-5", "harness": "claude-code", "runs": 12, "one_shot": 11,
+//         "first_at": "2026-09-01T09:00:00Z", "last_at": "2026-10-05T18:00:00Z" }
+//     ]
+//   }
+//
+// A run is one real use: never a sandbox run (`doctor --run`), never a test. It is one-shot when
+// the person needed no correction, rescue or redirect, it did not fail or get abandoned, and it
+// was not corrected after it handed back. A taste note is the person's preference, not a defect,
+// and does not break one-shot.
+//
+// Where the doctor reads it, first found wins:
+//   1. <dir>/<skill-name>.json, where <dir> is --real-runs or SUPERSKILL_REAL_RUNS (an
+//      operator's own export, kept out of the skill);
+//   2. <skill>/evals/real-runs.json (counts only, so it can travel with the skill);
+//   3. Freedom's skill ledger, read as plain files, when neither exists.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { ledgerPaths } from "./ledger.mjs";
+
+export const FORMAT = "superskill-real-runs/1";
+export const UNKNOWN = "unknown";
+/** The defaults the real-runs rule holds a skill to. `--min-real-runs` / `--min-one-shot` change them. */
+export const MIN_REAL_RUNS = 5;
+export const MIN_ONE_SHOT = 0.8;
+
+const MISS_KINDS = new Set(["redirect", "correction", "rescue"]);
+
+/** Is this a known model+harness pair? A record that could not say proves nothing about either. */
+export const knownPair = (p) => Boolean(p.model && p.harness && p.model !== UNKNOWN && p.harness !== UNKNOWN);
+
+function normalize(doc, where) {
+  if (!doc || typeof doc !== "object") return { error: `${where} is not a JSON object` };
+  if (doc.format && doc.format !== FORMAT) return { error: `${where} has format ${JSON.stringify(doc.format)}, not ${FORMAT}` };
+  if (!Array.isArray(doc.pairs)) return { error: `${where} has no pairs array` };
+  const pairs = doc.pairs
+    .filter((p) => p && typeof p === "object")
+    .map((p) => ({
+      model: String(p.model || UNKNOWN),
+      harness: String(p.harness || UNKNOWN),
+      runs: Math.max(0, Number(p.runs) || 0),
+      one_shot: Math.max(0, Number(p.one_shot) || 0),
+      first_at: p.first_at || null,
+      last_at: p.last_at || null,
+    }))
+    .map((p) => ({ ...p, one_shot: Math.min(p.one_shot, p.runs) }));
+  return { pairs, generated_at: doc.generated_at || null, source: doc.source || null, where };
+}
+
+function readFile(p, where) {
+  try { return normalize(JSON.parse(readFileSync(p, "utf8")), where); }
+  catch (e) { return { error: `${where} is not valid JSON: ${e.message}` }; }
+}
+
+/** Is a ledger record a one-shot run? Exported so a writer can count the same way the reader does. */
+export function isOneShot(rec) {
+  const kinds = (Array.isArray(rec?.interventions) ? rec.interventions : []).filter((i) => i && MISS_KINDS.has(i.kind));
+  return !kinds.length && !["failed", "abandoned"].includes(rec?.outcome) && !rec?.corrected_after;
+}
+
+/** Summarize ledger records (Freedom's shape, or any with model/harness/started) per model+harness. */
+export function pairsFromRecords(records, skillName = null) {
+  const by = new Map();
+  for (const rec of records) {
+    if (!rec || rec.synthetic) continue;
+    if (skillName && rec.skill && bare(rec.skill) !== bare(skillName)) continue;
+    const model = String(rec.model || UNKNOWN), harness = String(rec.harness || UNKNOWN);
+    const k = `${model}\u0000${harness}`;
+    const p = by.get(k) || { model, harness, runs: 0, one_shot: 0, first_at: null, last_at: null };
+    p.runs++;
+    if (isOneShot(rec)) p.one_shot++;
+    const t = typeof rec.started === "string" ? rec.started : null;
+    if (t && (!p.first_at || t < p.first_at)) p.first_at = t;
+    if (t && (!p.last_at || t > p.last_at)) p.last_at = t;
+    by.set(k, p);
+  }
+  return [...by.values()].sort((a, b) => b.runs - a.runs || a.model.localeCompare(b.model));
+}
+
+const bare = (name) => String(name || "").split(":").pop();
+
+function fromLedger(dir, name) {
+  const paths = ledgerPaths(dir, name);
+  if (!paths.length) return null;
+  const recs = [];
+  for (const p of paths) {
+    let text = "";
+    try { text = readFileSync(p, "utf8"); } catch { continue; }
+    for (const line of text.split("\n")) {
+      if (!line.trim()) continue;
+      try { recs.push(JSON.parse(line)); } catch {}
+    }
+  }
+  return { pairs: pairsFromRecords(recs, name), generated_at: null, source: "freedom-skill-ledger (read live)", where: "Freedom's skill ledger" };
+}
+
+/** The real-run record for one skill, or null when nothing records any. */
+export function readRealRuns(dir, { name, realRunsDir = null } = {}) {
+  if (realRunsDir && name) {
+    const p = join(realRunsDir, `${name}.json`);
+    if (existsSync(p)) return readFile(p, `${realRunsDir}/${name}.json`);
+  }
+  const local = join(dir, "evals", "real-runs.json");
+  if (existsSync(local)) return readFile(local, "evals/real-runs.json");
+  return fromLedger(dir, name);
+}
+
+/** Does any single pair clear the bar? Never pooled: each pair stands or falls on its own runs. */
+export function meetsBar(pairs, { minRuns = MIN_REAL_RUNS, minOneShot = MIN_ONE_SHOT } = {}) {
+  return pairs.filter(knownPair).filter((p) => p.runs >= minRuns && p.one_shot / p.runs >= minOneShot);
+}

package/src/rules/skill.mjs

@@ -26,6 +26,63 @@ function proseLines(body) {
     return { line, fenced };
   });
 }
+// A dated incident story, as written in real skills: "Earned 2026-09-08", "(Gary, 2026-09-16:
+// ...)", "Wilson, live, 2026-09-05: *"...", "on 2026-09-13 the in-process version sat...",
+// "until 2026-09-21 the flag...", "measured on 2026-09-20", "(2026-09-30, #324)",
+// "- 2026-09-15 (#147): ...". Matched per paragraph, because hard-wrapped prose puts the name on
+// one line and its date on the next. Tuned against Freedom's 103 shipped skills (2026-10-06): a
+// date in an example, a template, a code span, a fence, or a provenance line ending at the date
+// ("vendored ... on 2026-09-19.") is not a story.
+const D = "20\\d\\d-\\d\\d-\\d\\d";
+const HISTORY = [
+  new RegExp(`\\bearned\\b[^.]{0,24}?\\b(${D})`, "gi"),
+  new RegExp(`\\([^()\\n]{0,80}?\\b(${D})\\s*[:),.;—]`, "g"),
+  new RegExp(`(?:\\b[A-Z][\\w'-]+|\\b(?:operator|owner|maintainer|client|teammate)),\\s*(?:[a-z]+,\\s*)?(${D})\\s*[,:]`, "g"),
+  new RegExp(`\\b(?:on|until|since|before|after)\\s+(${D})\\b`, "gi"),
+  new RegExp(`\\bfrom\\s+(${D})\\s+\\(`, "gi"),
+  new RegExp(`\\b(?:measured|reported|found|caught|hit|corrected|retired|aligned|renamed|refused|broke|failed|observed|verified|watched|fixed|softened|flipped|restored|removed|changed|added|introduced)\\s+(?:[a-z]+\\s+)?(?:on\\s+|in\\s+)?(${D})`, "gi"),
+  new RegExp(`\\b(?:rule|ruling|default|correction|incident|reversal)\\s+(?:of|from)\\s+(${D})`, "gi"),
+  new RegExp(`\\bthe\\s+(${D})\\b`, "gi"),
+  new RegExp(`(${D})'s\\b`, "g"),
+  new RegExp(`^\\s*[-*]\\s+[*_]*(${D})[*_]*\\s*[(:]`, "gm"),
+];
+const EXAMPLE = /\b(e\.g\.|example|for instance|such as)\b/i;
+
+/**
+ * Body lines that narrate a dated incident, outside code fences and inline code: one entry per
+ * line that carries the date of a story.
+ */
+export function historyLines(body) {
+  const lines = proseLines(body);
+  const hit = new Map();
+  let para = [];
+  const flush = () => {
+    if (!para.length) return;
+    // Join the paragraph, remembering where each line starts, so a match maps back to its line.
+    let text = "";
+    const starts = [];
+    for (const { i, line } of para) { starts.push({ i, at: text.length }); text += line.replace(/`[^`]*`/g, "``") + "\n"; }
+    for (const re of HISTORY) {
+      re.lastIndex = 0;
+      for (const m of text.matchAll(re)) {
+        const at = m.index + m[0].lastIndexOf(m[1]);
+        const owner = [...starts].reverse().find((s) => s.at <= at);
+        const raw = lines[owner.i].line;
+        if (EXAMPLE.test(raw)) continue;
+        if (!hit.has(owner.i)) hit.set(owner.i, raw.trim());
+      }
+    }
+    para = [];
+  };
+  lines.forEach(({ line, fenced }, i) => {
+    // A heading, an HTML comment (a generator's provenance stamp) and a fence are not prose.
+    if (fenced || !line.trim() || /^\s*(#|<!--)/.test(line)) { flush(); return; }
+    para.push({ i, line });
+  });
+  flush();
+  return [...hit.entries()].sort((a, b) => a[0] - b[0]).map(([i, text]) => ({ lineNo: i + 1, text }));
+}
+
 const normRule = (line) => line.toLowerCase().replace(/[*_`>#-]/g, "").replace(/\s+/g, " ").trim();
 const broken = (ctx) => Boolean(ctx.error || ctx.parseError);
 const str = (v) => (typeof v === "string" ? v : "");
@@ -194,6 +251,20 @@ export const skillRules = defineRules([
       return [f("warn", `${late.length} hard rule(s) sit past the first ~${FOLD_TOKENS} tokens and would not survive compaction (${shown})`, "Restate them in a short Rules section near the top, or move them up. Length is fine; the rules just need to be above the fold. Step-specific detail can move into step files (steps/<step>.md) that are read fresh when the step comes up.")];
     },
   },
+  {
+    // 0.6.0: SKILL.md is instructions, read on every run. The story of the incident that earned
+    // a rule is history: it belongs in MISSES.md, under the miss it records, and SKILL.md keeps
+    // the rule and a one-line why. Anthropic's authoring guidance: avoid time-sensitive content.
+    id: "history-in-skill",
+    level: "skill",
+    check(ctx) {
+      if (broken(ctx)) return [];
+      const hits = historyLines(ctx.body);
+      if (!hits.length) return [];
+      const shown = hits.slice(0, 3).map((h) => `line ${h.lineNo + ctx.bodyStartLine - 1}: ${h.text.slice(0, 70)}`).join("; ");
+      return [f("warn", `${hits.length} dated incident stor${hits.length === 1 ? "y" : "ies"} in SKILL.md (${shown})`, "Move each story into MISSES.md as a miss entry (id, date, what happened, fix, eval, optional quote) and leave the rule plus a one-line why in SKILL.md.")];
+    },
+  },
   {
     id: "navigable",
     level: "skill",