@supersuit/superskill 0.1.0

package/src/evals.mjs

@@ -0,0 +1,44 @@
+// Readers for evals/evals.json and evals/triggers.json. Both follow Anthropic's
+// skill-creator formats: evals.json is {skill_name, evals: [{id, prompt, expected_output,
+// files, expectations}]}; triggers.json is [{query, should_trigger}]. On read we also
+// accept `assertions` for `expectations` and a bare array for evals.json.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+function readJson(path) {
+  if (!existsSync(path)) return { missing: true };
+  try { return { value: JSON.parse(readFileSync(path, "utf8")) }; }
+  catch (e) { return { error: `${e.message}` }; }
+}
+
+export function readEvals(dir) {
+  const r = readJson(join(dir, "evals", "evals.json"));
+  if (r.missing) return { missing: true, cases: [] };
+  if (r.error) return { error: `evals/evals.json is not valid JSON: ${r.error}`, cases: [] };
+  const list = Array.isArray(r.value) ? r.value : Array.isArray(r.value?.evals) ? r.value.evals : null;
+  if (!list) return { error: "evals/evals.json has no evals array", cases: [] };
+  const cases = list.map((c, i) => ({
+    id: c?.id ?? i + 1,
+    prompt: typeof c?.prompt === "string" ? c.prompt : "",
+    expected_output: c?.expected_output ?? "",
+    files: Array.isArray(c?.files) ? c.files : [],
+    assertions: Array.isArray(c?.expectations) ? c.expectations : Array.isArray(c?.assertions) ? c.assertions : [],
+  }));
+  return { cases, skill_name: r.value?.skill_name };
+}
+
+export function readTriggers(dir) {
+  const r = readJson(join(dir, "evals", "triggers.json"));
+  if (r.missing) return { missing: true, triggers: [] };
+  if (r.error) return { error: `evals/triggers.json is not valid JSON: ${r.error}`, triggers: [] };
+  const list = Array.isArray(r.value) ? r.value : Array.isArray(r.value?.triggers) ? r.value.triggers : null;
+  if (!list) return { error: "evals/triggers.json is not a list of {query, should_trigger}", triggers: [] };
+  return { triggers: list.filter((t) => t && typeof t.query === "string").map((t) => ({ query: t.query, should_trigger: t.should_trigger === true })) };
+}
+
+export function readLatestRun(dir) {
+  const r = readJson(join(dir, "evals", "results", "latest.json"));
+  if (r.missing) return { missing: true };
+  if (r.error) return { error: `evals/results/latest.json is not valid JSON: ${r.error}` };
+  return { run: r.value };
+}

package/src/frontmatter.mjs

@@ -0,0 +1,109 @@
+// A small YAML frontmatter reader for the subset SKILL.md files use: scalars, quoted
+// strings, folded (>) and literal (|) blocks, one-level maps, inline and block lists.
+// Values stay strings; rules decide what a string means. Zero dependencies on purpose.
+
+export function parseSkillFile(text) {
+  const src = String(text).replace(/\r\n?/g, "\n");
+  const lines = src.split("\n");
+  if (lines[0].trim() !== "---") return { data: {}, body: src, bodyStartLine: 1, error: "no frontmatter" };
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") { end = i; break; }
+  }
+  if (end === -1) return { data: {}, body: "", bodyStartLine: 1, error: "unterminated frontmatter" };
+  let data;
+  try {
+    data = parseYamlSubset(lines.slice(1, end));
+  } catch (e) {
+    return { data: {}, body: lines.slice(end + 1).join("\n"), bodyStartLine: end + 2, error: `frontmatter: ${e.message}` };
+  }
+  return { data, body: lines.slice(end + 1).join("\n"), bodyStartLine: end + 2 };
+}
+
+const indentOf = (l) => l.length - l.trimStart().length;
+
+export function parseYamlSubset(lines) {
+  const out = {};
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith("#")) { i++; continue; }
+    if (indentOf(line) > 0) { i++; continue; } // stray indented line: tolerate
+    const m = line.match(/^([^:\s][^:]*?)\s*:(?:\s+(.*)|\s*)$/);
+    if (!m) throw new Error(`cannot read line ${i + 1}: ${line.slice(0, 60)}`);
+    const key = m[1].trim().replace(/^["']|["']$/g, "");
+    const rest = (m[2] ?? "").trim();
+    i++;
+    if (/^[>|][+-]?$/.test(rest)) {
+      const block = [];
+      while (i < lines.length && (lines[i].trim() === "" || indentOf(lines[i]) > 0)) { block.push(lines[i]); i++; }
+      while (block.length && !block[block.length - 1].trim()) block.pop();
+      const min = Math.min(...block.filter((l) => l.trim()).map(indentOf));
+      const stripped = block.map((l) => l.slice(Number.isFinite(min) ? min : 0));
+      out[key] = rest[0] === "|" ? stripped.join("\n") : foldLines(stripped);
+      continue;
+    }
+    if (rest === "") {
+      const child = [];
+      while (i < lines.length && (lines[i].trim() === "" || indentOf(lines[i]) > 0 || lines[i].trimStart().startsWith("- "))) {
+        if (indentOf(lines[i]) === 0 && lines[i].trim() && !lines[i].startsWith("- ")) break;
+        child.push(lines[i]); i++;
+      }
+      const items = child.filter((l) => l.trim() && !l.trim().startsWith("#"));
+      if (!items.length) out[key] = "";
+      else if (items[0].trim().startsWith("- ") || items[0].trim() === "-") out[key] = items.map((l) => scalar(l.trim().replace(/^-\s*/, "")));
+      else {
+        const map = {};
+        const base = indentOf(items[0]);
+        for (const l of items) {
+          if (indentOf(l) !== base) continue; // deeper nesting is outside the subset; ignored
+          const mm = l.trim().match(/^([^:]+?)\s*:\s*(.*)$/);
+          if (mm) map[mm[1].trim().replace(/^["']|["']$/g, "")] = scalar(mm[2]);
+        }
+        out[key] = map;
+      }
+      continue;
+    }
+    if (rest.startsWith("[") && rest.endsWith("]")) {
+      out[key] = splitInline(rest.slice(1, -1)).map(scalar).filter((s) => s !== "");
+      continue;
+    }
+    out[key] = scalar(rest);
+  }
+  return out;
+}
+
+function foldLines(lines) {
+  let s = "";
+  for (const l of lines) {
+    if (!l.trim()) s += "\n";
+    else s += (s && !s.endsWith("\n") ? " " : "") + l.trim();
+  }
+  return s;
+}
+
+function splitInline(s) {
+  const parts = [];
+  let cur = "", q = null;
+  for (const ch of s) {
+    if (q) { cur += ch; if (ch === q) q = null; }
+    else if (ch === '"' || ch === "'") { q = ch; cur += ch; }
+    else if (ch === ",") { parts.push(cur); cur = ""; }
+    else cur += ch;
+  }
+  parts.push(cur);
+  return parts.map((p) => p.trim());
+}
+
+function scalar(raw) {
+  const s = String(raw).trim();
+  if (s.startsWith('"')) {
+    const end = s.lastIndexOf('"');
+    try { return JSON.parse(s.slice(0, end + 1)); } catch { return s.slice(1, end > 0 ? end : undefined); }
+  }
+  if (s.startsWith("'")) {
+    const end = s.lastIndexOf("'");
+    return s.slice(1, end > 0 ? end : undefined).replace(/''/g, "'");
+  }
+  return s.replace(/\s+#.*$/, "");
+}

package/src/goldens.mjs

@@ -0,0 +1,34 @@
+// goldens/<id>/: input.md, the approved output (output.md, or any other non-input file),
+// and APPROVAL.json {approved_by, approved_at, skill_sha, note} written by a person.
+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 [];
+  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; }
+    }
+    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,
+      approvalError,
+    });
+  }
+  return out;
+}
+
+export const isApproved = (g) => Boolean(g.approval && typeof g.approval.approved_by === "string" && g.approval.approved_by.trim() && g.approval.approved_at && !Number.isNaN(new Date(g.approval.approved_at).getTime()));

package/src/ledger.mjs

@@ -0,0 +1,44 @@
+// Freedom's run ledger, read as plain files. Freedom records every skill run; a run that
+// needed a correction, a rescue or a redirect, or that failed, is a miss the skill owes a fix
+// for. Taste corrections are the operator's preference, not the skill's defect, and are skipped.
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const MISS_KINDS = new Set(["redirect", "correction", "rescue"]);
+
+/** Ledger files that may hold runs of this skill. */
+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");
+  if (existsSync(root) && skillName) {
+    for (const plugin of readdirSync(root).sort()) {
+      const p = join(root, plugin, `${skillName}.jsonl`);
+      if (existsSync(p)) out.push(p);
+    }
+  }
+  return out;
+}
+
+/** Misses to import from one ledger file, skipping ledger ids already in `known`. */
+export function ledgerMisses(path, known, skillName) {
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    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;
+    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("; ")})` : ""}`);
+    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}` });
+    known.add(rec.id);
+  }
+  return out;
+}

package/src/levels.mjs

@@ -0,0 +1,38 @@
+export const LEVELS = ["skill", "tested", "superskill"];
+
+/** Next level up from a reached level, or null at the top. */
+export function nextLevel(level) {
+  if (level === "none") return "skill";
+  const i = LEVELS.indexOf(level);
+  return i >= 0 && i < LEVELS.length - 1 ? LEVELS[i + 1] : null;
+}
+
+/** True when `reached` is at or above `target`. */
+export function meets(reached, target) {
+  return reached !== "none" && LEVELS.indexOf(reached) >= LEVELS.indexOf(target);
+}
+
+/** A level is reached when it and every level below it have no `fail` finding. */
+export function computeLevel(findings) {
+  let reached = "none";
+  for (const level of LEVELS) {
+    if (findings.some((f) => f.level === level && f.severity === "fail")) break;
+    reached = level;
+  }
+  return reached;
+}
+
+/** Run rules against a context, tagging every finding with the rule's id and level. */
+export function runRules(ctx, rules, opts = {}) {
+  const out = [];
+  for (const r of rules) {
+    let found;
+    try {
+      found = r.check(ctx, opts) || [];
+    } catch (e) {
+      found = [{ severity: "fail", message: `rule crashed: ${e.message}`, fix: "Report this as a superskill bug." }];
+    }
+    for (const f of found) out.push({ ...f, rule: f.rule || r.id, level: r.level });
+  }
+  return out;
+}

package/src/misses.mjs

@@ -0,0 +1,88 @@
+// MISSES.md: one dated entry per time the skill got something wrong.
+//
+//   ## m1 · 2026-09-20 · fixed
+//   - What happened: ...
+//   - Should have: ...
+//   - Fix: <commit sha or note>
+//   - Eval: m1
+//   - 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.
+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" };
+
+export function parseMisses(text) {
+  const out = [];
+  let cur = 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 };
+      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();
+    }
+  });
+  return out;
+}
+
+export function readMisses(dir) {
+  const p = join(dir, "MISSES.md");
+  if (!existsSync(p)) return null;
+  return parseMisses(readFileSync(p, "utf8"));
+}
+
+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.source) lines.push(`- Source: ${m.source}`);
+  return lines.join("\n") + "\n";
+}
+
+export function nextMissId(misses) {
+  const n = misses.reduce((max, m) => Math.max(max, Number(m.id.slice(1)) || 0), 0);
+  return `m${n + 1}`;
+}
+
+/** Append entries to MISSES.md, creating it with its header when absent. */
+export function appendMisses(dir, entries) {
+  const p = join(dir, "MISSES.md");
+  let text = existsSync(p) ? readFileSync(p, "utf8") : MISSES_HEADER;
+  if (!text.endsWith("\n")) text += "\n";
+  for (const e of entries) text += "\n" + formatMiss(e);
+  writeFileSync(p, text);
+}
+
+/** Rewrite one entry in place (status, fix, eval), leaving the rest of the file byte-identical. */
+export function updateMiss(dir, id, patch) {
+  const p = join(dir, "MISSES.md");
+  const lines = readFileSync(p, "utf8").split("\n");
+  const start = lines.findIndex((l) => { const h = l.match(HEAD_RE); return h && h[1].toLowerCase() === id; });
+  if (start < 0) return false;
+  let end = lines.findIndex((l, i) => i > start && /^##\s/.test(l));
+  if (end < 0) end = lines.length;
+  const [cur] = parseMisses(lines.slice(start, end).join("\n"));
+  const next = { ...cur, ...patch };
+  let block = formatMiss(next).replace(/\n$/, "").split("\n");
+  // keep any trailing blank lines the original block had
+  const tail = [];
+  for (let i = end - 1; i > start && lines[i].trim() === ""; i--) tail.push("");
+  lines.splice(start, end - start, ...block, ...tail);
+  writeFileSync(p, lines.join("\n"));
+  return true;
+}

package/src/report.mjs

@@ -0,0 +1,27 @@
+import { nextLevel, LEVELS } from "./levels.mjs";
+import { pluginLines } from "./commands/collection.mjs";
+
+/** Human-readable doctor report: level, what to fix now, and the to-do list for the next level. */
+export function formatDoctor(result) {
+  const lines = [];
+  for (const s of result.skills) {
+    lines.push(`${s.name}  level: ${s.level}`);
+    lines.push(`  ${s.path}`);
+    // fails never sit at or below the reached level, so they all belong to the to-do list
+    const shown = s.findings.filter((f) => f.severity !== "fail");
+    for (const f of shown) lines.push(`  ${f.severity.padEnd(4)}  ${f.rule}: ${f.message}`);
+    const up = nextLevel(s.level);
+    if (up && s.next.length) {
+      lines.push(`  to reach ${up}:`);
+      for (const f of s.next) lines.push(`    - ${f.rule}: ${f.message}\n      fix: ${f.fix}`);
+    } else if (!up) lines.push("  top level reached");
+    lines.push("");
+  }
+  const counts = Object.fromEntries(["none", ...LEVELS].map((l) => [l, 0]));
+  for (const s of result.skills) counts[s.level]++;
+  const summary = ["superskill", "tested", "skill", "none"].filter((l) => counts[l]).map((l) => `${counts[l]} ${l}`).join(", ");
+  if (result.plugin) lines.push(...pluginLines(result.plugin, result.plugin.superplugin), "");
+  lines.push(`${result.skills.length} skill${result.skills.length === 1 ? "" : "s"}: ${summary}. target ${result.target}: ${result.ok ? "met" : "not met"}`);
+  return lines.join("\n") + "\n";
+}
+

package/src/rules/define.mjs

@@ -0,0 +1,9 @@
+/** Wrap rule definitions so every finding a check returns names its rule. */
+export function defineRules(rules) {
+  return rules.map((r) => ({
+    ...r,
+    check(ctx, opts = {}) {
+      return (r.check(ctx, opts) || []).map((x) => ({ rule: r.id, ...x }));
+    },
+  }));
+}

package/src/rules/index.mjs

@@ -0,0 +1,7 @@
+import { skillRules } from "./skill.mjs";
+import { testedRules } from "./tested.mjs";
+import { superskillRules } from "./superskill.mjs";
+import { interopRules } from "./interop.mjs";
+
+/** Every rule the doctor runs, in report order. */
+export const allRules = [...skillRules, ...testedRules, ...superskillRules, ...interopRules];

package/src/rules/interop.mjs

@@ -0,0 +1,13 @@
+// Bonus lines for files other harnesses keep beside a skill. Never required, never a fail.
+import { defineRules } from "./define.mjs";
+
+export const interopRules = defineRules([
+  {
+    id: "workflow-map",
+    level: "skill",
+    check(ctx) {
+      if (ctx.error || !ctx.files.includes("HDSOP.md")) return [];
+      return [{ severity: "info", message: "workflow map (HDSOP.md) present", fix: "Nothing to do; this is a bonus." }];
+    },
+  },
+]);