@skill-harness/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mojo Manyana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/report.grade.js

@@ -0,0 +1,77 @@
+// Client-side scorer for the review UI (assets/report.template.html).
+//
+// This is the SINGLE source of truth for "how does a column get graded in the
+// browser" — it must implement exactly the same rules as
+// packages/core/src/score.ts's `score()`. It is:
+//   (a) imported directly, as plain ESM, by
+//       packages/core/test/grade-column-parity.test.ts, which asserts parity
+//       against score.ts for a set of fixtures (PASS/FAIL/critical/B-series/
+//       suspect/override-resolved-suspect). If you change score.ts's rules
+//       and forget to mirror them here, that test fails.
+//   (b) injected verbatim into report.template.html's inline <script>, at the
+//       GRADE placeholder comment near its top (see renderReport in
+//       packages/core/src/report.ts).
+//
+// INJECTION NOTE: a bare inline <script> (no type="module") cannot contain an
+// `export` statement. renderReport() strips the leading `export ` keyword off
+// each exported declaration textually before splicing this file's contents
+// into the template. Nothing here relies on import/export semantics at
+// runtime (no imports, no re-exports), so stripping `export ` and leaving
+// plain function declarations behind is safe in both the browser (global
+// script scope) and Node (this file imported as an ES module).
+//
+// No DOM access, no imports — must load in Node (for the parity test) and in
+// a plain <script> in the browser (for the review UI).
+
+export function effective(cell) {
+  return cell.override || cell.judge_verdict;
+}
+
+function letterFor(pct) {
+  if (pct >= 90) return "A";
+  if (pct >= 80) return "B";
+  if (pct >= 70) return "C";
+  if (pct >= 60) return "D";
+  return "F";
+}
+
+/**
+ * Score one report column against the ship bar — mirrors score.ts's `score()`
+ * exactly, over `col.cells` (a scenario-id -> cell map) instead of a flat
+ * verdict list. A `suspect` cell without an override is excluded from both
+ * `passed` and `total` (untrustworthy: neither pass nor fail) and blocks ship.
+ */
+export function gradeColumn(col, shipBar, critical) {
+  let passed = 0;
+  let total = 0;
+  let criticalFails = 0;
+  let bFails = 0;
+  let suspect = 0;
+
+  for (const id of Object.keys(col.cells)) {
+    const cell = col.cells[id];
+    if (!cell) continue;
+    if (cell.suspect && !cell.override) {
+      suspect++;
+      continue; // excluded, blocks ship
+    }
+    total++;
+    if (effective(cell) === "PASS") {
+      passed++;
+      continue;
+    }
+    if (critical.includes(id)) criticalFails++;
+    if (/^B/i.test(id)) bFails++;
+  }
+
+  const pct = total > 0 ? Math.round((passed * 100) / total) : 0;
+  const letter = letterFor(pct);
+  const ship =
+    total >= shipBar.total &&
+    passed >= shipBar.min_pass &&
+    (!shipBar.no_critical_fail || criticalFails === 0) &&
+    bFails === 0 &&
+    suspect === 0;
+
+  return { passed, total, pct, letter, ship, criticalFails, bFails, suspect };
+}

package/assets/report.template.html

@@ -0,0 +1,336 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>skill-harness · __SKILL__</title>
+<style>
+  :root {
+    --bg: #0f1115; --panel: #171a21; --line: #262b36; --fg: #e6e9ef; --dim: #9aa3b2;
+    --pass: #1f8b4c; --fail: #c0392b; --err: #6b7280; --accent: #4f8cff; --over: #d28b00;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, sans-serif; }
+  header { padding: 16px 20px; border-bottom: 1px solid var(--line); display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap; }
+  header h1 { font-size: 18px; margin: 0; font-weight: 650; }
+  header .sub { color: var(--dim); font-size: 13px; }
+  main { display: flex; min-height: calc(100vh - 58px); }
+  .matrix-wrap { flex: 1; overflow: auto; padding: 16px 20px; }
+  table { border-collapse: collapse; width: 100%; }
+  th, td { border: 1px solid var(--line); padding: 8px 10px; text-align: left; vertical-align: top; }
+  th { background: var(--panel); font-weight: 600; position: sticky; top: 0; }
+  th.scn, td.scn { position: sticky; left: 0; background: var(--panel); z-index: 1; min-width: 200px; }
+  .crit { color: var(--over); margin-left: 4px; }
+  .cell { cursor: pointer; text-align: center; font-weight: 650; min-width: 90px; user-select: none; }
+  .cell.PASS { background: rgba(31,139,76,.22); }
+  .cell.FAIL { background: rgba(192,57,43,.24); }
+  .cell.ERROR { background: rgba(107,114,128,.22); }
+  .cell.empty { color: var(--dim); cursor: default; font-weight: 400; }
+  .cell .ov { display: block; font-size: 11px; color: var(--over); font-weight: 600; }
+  .cell .ov.unsaved { color: #b45309; font-style: italic; }
+  .cell .ov.suspect { color: #b45309; }
+  .cell .reps { display: block; font-size: 10px; color: var(--dim); }
+  .cell.sel { outline: 2px solid var(--accent); outline-offset: -2px; }
+  .grade { font-size: 12px; color: var(--dim); font-weight: 500; margin-top: 4px; }
+  .badge { display: inline-block; padding: 1px 7px; border-radius: 999px; font-size: 11px; font-weight: 700; }
+  .badge.ship { background: var(--pass); color: #fff; }
+  .badge.no { background: var(--fail); color: #fff; }
+  aside { width: 0; transition: width .15s ease; overflow: hidden; border-left: 1px solid var(--line); background: var(--panel); }
+  aside.open { width: 460px; }
+  .panel { width: 460px; padding: 16px 18px; }
+  .panel h2 { font-size: 15px; margin: 0 0 2px; }
+  .panel .meta { color: var(--dim); font-size: 12px; margin-bottom: 12px; }
+  .panel .reason { background: #11141a; border: 1px solid var(--line); border-radius: 6px; padding: 8px 10px; margin-bottom: 12px; }
+  .toggle { display: flex; gap: 8px; margin-bottom: 12px; }
+  .toggle button { flex: 1; padding: 7px; border: 1px solid var(--line); background: #11141a; color: var(--fg); border-radius: 6px; cursor: pointer; font-weight: 600; }
+  .toggle button.active.PASS { background: var(--pass); border-color: var(--pass); color: #fff; }
+  .toggle button.active.FAIL { background: var(--fail); border-color: var(--fail); color: #fff; }
+  .toggle button.active.JUDGE { background: var(--accent); border-color: var(--accent); color: #fff; }
+  textarea { width: 100%; min-height: 60px; background: #11141a; color: var(--fg); border: 1px solid var(--line); border-radius: 6px; padding: 8px; font: inherit; resize: vertical; }
+  label.fld { display: block; font-size: 12px; color: var(--dim); margin: 10px 0 4px; }
+  pre.transcript { white-space: pre-wrap; word-break: break-word; background: #0b0d11; border: 1px solid var(--line); border-radius: 6px; padding: 10px; max-height: 42vh; overflow: auto; font: 12px/1.5 ui-monospace, monospace; }
+  .saved { color: var(--pass); font-size: 12px; margin-left: 8px; opacity: 0; transition: opacity .2s; }
+  .saved.show { opacity: 1; }
+  .saved.err { color: #b91c1c; opacity: 1; }
+  .close { float: right; cursor: pointer; color: var(--dim); border: none; background: none; font-size: 18px; }
+  .empty-state { color: var(--dim); padding: 40px; text-align: center; }
+  #misfires { margin: 0 0 16px; }
+  .mf-title { font-weight: 600; margin-bottom: 6px; }
+  .mf-title.empty { color: var(--dim); font-weight: 400; }
+  .mf-row { padding: 4px 0; border-bottom: 1px solid var(--line, #eee); font-size: 13px; }
+  .rejudge { margin: 8px 0; }
+  .rejudge button { cursor: pointer; }
+  #trends-section { margin-top: 20px; }
+  #trends-toggle { cursor: pointer; font-weight: 600; background: none; border: none; font-size: 14px; }
+  .tmodel { margin: 12px 0; }
+  .tmodel-h { font-size: 13px; margin-bottom: 4px; }
+  .spark { vertical-align: middle; color: var(--dim, #888); }
+  table.tgrid { border-collapse: collapse; font-size: 12px; }
+  /* The trends grid is a compact read-only summary, not the interactive matrix
+     above — it deliberately opts out of the matrix's sticky-header/sticky-
+     first-column rules (`position: sticky`) so a future CSS consolidation
+     doesn't reintroduce the 094a219 bug (trends scrolling under a stuck header). */
+  .tgrid th, .tgrid td { padding: 2px 6px; text-align: center; position: static; }
+  .tgrid td.tscn { text-align: left; }
+  .tgrid td.tc.PASS { color: #16a34a; }
+  .tgrid td.tc.FAIL { color: #dc2626; }
+  .tgrid td.tc.ERROR { color: #a855f7; }
+  .tgrid td.tc.suspect { color: #b45309; }
+  .tgrid td.tc.absent { color: var(--dim, #bbb); }
+  .dim { color: var(--dim, #888); font-weight: 400; }
+</style>
+</head>
+<body>
+<header>
+  <h1>skill-harness</h1>
+  <span class="sub" id="subtitle"></span>
+</header>
+<main>
+  <div class="matrix-wrap">
+    <div id="misfires"></div>
+    <div id="matrix"></div>
+    <div id="trends-section">
+      <button id="trends-toggle">▸ Trends</button>
+      <div id="trends" hidden></div>
+    </div>
+  </div>
+  <aside id="aside"><div class="panel" id="panel"></div></aside>
+</main>
+
+<script>
+const DATA = /*__DATA__*/null;
+
+// effective()/gradeColumn() are injected here from assets/report.grade.js —
+// the single, tested copy of the client scorer (mirrors src/score.ts). See
+// renderReport() in packages/core/src/report.ts for how the injection works.
+/*__GRADE__*/
+
+let selected = null; // { colIndex, scenarioId }
+
+function render() {
+  document.getElementById("subtitle").textContent =
+    `${DATA.skill} · ${DATA.columns.length} model(s) · ship bar ${DATA.shipBar.min_pass}/${DATA.shipBar.total}, no critical fail`;
+  const wrap = document.getElementById("matrix");
+  if (!DATA.columns.length) {
+    wrap.innerHTML = `<div class="empty-state">No runs yet for <b>${DATA.skill}</b>.<br>Run <code>skill-harness run ${DATA.skill}</code> first.</div>`;
+    return;
+  }
+  const grades = DATA.columns.map((col) => gradeColumn(col, DATA.shipBar, DATA.critical));
+  const queue = [];
+  DATA.columns.forEach((col) => {
+    // A suspect cell in a red/force column can't be re-judged (/rejudge 400s
+    // "only green runs can be re-judged") — don't queue it. The matrix below
+    // still shows suspect badges for every column regardless of mode.
+    if (col.mode && col.mode !== "green") return;
+    for (const scn of DATA.scenarios) {
+      const cell = col.cells[scn.id];
+      if (cell && cell.suspect && !cell.override) queue.push({ col: col.index, id: scn.id, label: col.label, reason: cell.judge_reason });
+    }
+  });
+  const mf = document.getElementById("misfires");
+  if (mf) {
+    mf.innerHTML = queue.length
+      ? `<div class="mf-title">⚠ Misfire queue (${queue.length})</div>` + queue.map((q) =>
+          `<div class="mf-row" data-col="${q.col}" data-id="${escapeHtml(q.id)}"><b>${escapeHtml(q.id)}</b> · ${escapeHtml(q.label)} — ${escapeHtml(q.reason || "(no reason)")} <button class="mf-open">inspect</button></div>`
+        ).join("")
+      : `<div class="mf-title empty">No unresolved misfires.</div>`;
+    mf.querySelectorAll(".mf-row").forEach((row) => {
+      row.querySelector(".mf-open").onclick = () => openPanel(+row.dataset.col, row.dataset.id);
+    });
+  }
+  let html = "<table><thead><tr><th class='scn'>scenario</th>";
+  DATA.columns.forEach((col, i) => {
+    const g = grades[i];
+    let gradeHtml;
+    if (col.mode && col.mode !== "green") {
+      // Only green runs are scored; a red/force column has no ship grade.
+      gradeHtml = `<span class='badge no'>not scored (${escapeHtml(col.mode)})</span>`;
+      if (g.suspect > 0) gradeHtml += ` — ${g.suspect} suspect`;
+    } else {
+      // g.ship is already false whenever g.suspect > 0 (gradeColumn's suspect gate), so
+      // the NOT READY badge is forced automatically; we just surface the count here.
+      const badge = g.ship ? "<span class='badge ship'>SHIP</span>" : "<span class='badge no'>NOT READY</span>";
+      const suspectNote = g.suspect > 0 ? ` — ${g.suspect} suspect` : "";
+      gradeHtml = `${g.letter} (${g.pct}%) · ${g.passed}/${g.total}${suspectNote} ${badge}`;
+    }
+    html += `<th><div>${escapeHtml(col.label)}</div><div class='grade'>${gradeHtml}</div></th>`;
+  });
+  html += "</tr></thead><tbody>";
+  for (const scn of DATA.scenarios) {
+    html += `<tr><td class='scn'>${scn.id}${scn.critical ? "<span class='crit' title='critical'>⚠</span>" : ""}<div class='grade'>${escapeHtml(scn.title)}</div></td>`;
+    DATA.columns.forEach((col) => {
+      const cell = col.cells[scn.id];
+      if (!cell) { html += `<td class='cell empty'>–</td>`; continue; }
+      const v = effective(cell);
+      const sel = selected && selected.colIndex === col.index && selected.scenarioId === scn.id ? " sel" : "";
+      // _unsaved wins regardless of override value, so a failed *clear*
+      // (override → null) still shows the marker instead of looking persisted.
+      const ov = cell._unsaved
+        ? `<span class='ov unsaved'>unsaved</span>`
+        : (cell.override ? `<span class='ov'>override</span>` : "");
+      const misfired = cell.clean != null && cell.clean < cell.reps ? ` · ${cell.reps - cell.clean} misfired` : "";
+      const reps = cell.reps ? `<span class='reps'>${cell.passes}/${cell.clean}${misfired}${cell.flakiness ? ` · flaky ${cell.flakiness.toFixed(2)}` : ""}</span>` : "";
+      const suspectBadge = cell.suspect && !cell.override ? `<span class='ov suspect'>suspect</span>` : "";
+      html += `<td class='cell ${v}${sel}' data-col='${col.index}' data-id='${scn.id}'>${v}${ov}${suspectBadge}${reps}</td>`;
+    });
+    html += "</tr>";
+  }
+  html += "</tbody></table>";
+  wrap.innerHTML = html;
+  wrap.querySelectorAll(".cell:not(.empty)").forEach((td) => {
+    td.addEventListener("click", () => openPanel(+td.dataset.col, td.dataset.id));
+  });
+}
+
+async function openPanel(colIndex, scenarioId) {
+  selected = { colIndex, scenarioId };
+  render();
+  const col = DATA.columns.find((c) => c.index === colIndex);
+  const scn = DATA.scenarios.find((s) => s.id === scenarioId);
+  const cell = col.cells[scenarioId];
+  const aside = document.getElementById("aside");
+  const panel = document.getElementById("panel");
+  aside.classList.add("open");
+  const eff = effective(cell);
+  panel.innerHTML = `
+    <button class="close" id="closeBtn">×</button>
+    <h2>${scn.id} · ${escapeHtml(scn.title)}</h2>
+    <div class="meta">${escapeHtml(col.label)} · judge ${escapeHtml(col.judge.provider + ":" + col.judge.model)}</div>
+    <div class="reason"><b>judge:</b> ${cell.judge_verdict} — ${escapeHtml(cell.judge_reason || "(no reason)")}</div>
+    ${cell.suspect ? `<div class="reason" style="color:#b45309"><b>⚠ suspect:</b> judge listed no failed item — re-judge before trusting this FAIL</div>` : ""}
+    <div class="toggle">
+      <button data-v="PASS" class="PASS ${cell.override === 'PASS' ? 'active PASS' : ''}">PASS</button>
+      <button data-v="FAIL" class="FAIL ${cell.override === 'FAIL' ? 'active FAIL' : ''}">FAIL</button>
+      <button data-v="" class="JUDGE ${!cell.override ? 'active JUDGE' : ''}">use judge (${cell.judge_verdict})</button>
+    </div>
+    <div class="rejudge"><button id="rejudgeBtn">Re-judge (${escapeHtml(col.judge.provider + ":" + col.judge.model)})</button> <span class="saved" id="rejudged"></span></div>
+    <label class="fld">note <span class="saved" id="saved">saved ✓</span></label>
+    <textarea id="note" placeholder="why you overrode / what to fix in SKILL.md">${escapeHtml(cell.note || "")}</textarea>
+    <label class="fld">transcript</label>
+    <pre class="transcript" id="transcript">loading…</pre>
+    <label class="fld">judge raw</label>
+    <pre class="transcript" id="judgeraw">loading…</pre>
+  `;
+  document.getElementById("closeBtn").onclick = () => { aside.classList.remove("open"); selected = null; render(); };
+  panel.querySelectorAll(".toggle button").forEach((b) => {
+    b.onclick = () => { cell.override = b.dataset.v || null; save(col, scenarioId, cell); openPanel(colIndex, scenarioId); };
+  });
+  const rj = document.getElementById("rejudgeBtn");
+  if (rj) rj.onclick = async () => {
+    rj.disabled = true; rj.textContent = "re-judging…";
+    try {
+      const r = await fetch("/rejudge", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ col: colIndex, scenarioId }),
+      });
+      const body = await r.json().catch(() => ({}));
+      if (!r.ok) { const s = document.getElementById("rejudged"); if (s) { s.textContent = body.error || "re-judge failed"; s.classList.add("show", "err"); } rj.disabled = false; rj.textContent = "Re-judge"; return; }
+      location.reload(); // re-judge rewrote results.yaml; reload the fresh matrix + grades
+    } catch (e) { rj.disabled = false; rj.textContent = "Re-judge"; }
+  };
+  let t;
+  document.getElementById("note").addEventListener("input", (e) => {
+    cell.note = e.target.value;
+    clearTimeout(t);
+    t = setTimeout(() => save(col, scenarioId, cell), 500);
+  });
+  try {
+    const r = await fetch(`/transcript?col=${colIndex}&id=${encodeURIComponent(scenarioId)}`);
+    document.getElementById("transcript").textContent = r.ok ? await r.text() : "(transcript unavailable)";
+  } catch { document.getElementById("transcript").textContent = "(transcript unavailable)"; }
+  try {
+    const jr = await fetch(`/judge?col=${colIndex}&id=${encodeURIComponent(scenarioId)}`);
+    document.getElementById("judgeraw").textContent = jr.ok ? await jr.text() : "(judge output not captured)";
+  } catch { document.getElementById("judgeraw").textContent = "(judge output not captured)"; }
+}
+
+async function save(col, scenarioId, cell) {
+  const s = document.getElementById("saved");
+  // Optimistic: mark the cell unsaved until the server confirms. On a rejected
+  // save (e.g. note-less override → 400) the marker stays, so the matrix never
+  // shows an override as persisted when results.yaml still has it null. The
+  // local toggle is kept so typing a note then retriggers save.
+  cell._unsaved = true;
+  try {
+    const r = await fetch("/save", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ col: col.index, scenarioId, override: cell.override, note: cell.note }),
+    });
+    if (!r.ok) {
+      const body = await r.json().catch(() => ({}));
+      if (s) { s.textContent = body.error || "save failed"; s.classList.add("show", "err"); }
+    } else {
+      cell._unsaved = false;
+      if (s) { s.textContent = "saved ✓"; s.classList.remove("err"); s.classList.add("show"); setTimeout(() => s.classList.remove("show"), 1200); }
+    }
+  } catch (e) { console.error("save failed", e); }
+  render();
+}
+
+function escapeHtml(s) { return String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c])); }
+
+let trendsLoaded = false;
+document.getElementById("trends-toggle").onclick = async () => {
+  const box = document.getElementById("trends");
+  const btn = document.getElementById("trends-toggle");
+  const nowHidden = box.hasAttribute("hidden");
+  if (nowHidden) box.removeAttribute("hidden"); else box.setAttribute("hidden", "");
+  btn.textContent = (nowHidden ? "▾ Trends" : "▸ Trends");
+  if (nowHidden && !trendsLoaded) {
+    box.textContent = "loading…";
+    try {
+      const r = await fetch("/trends");
+      if (!r.ok) throw new Error(`trends fetch failed: ${r.status} ${await r.text().catch(() => "")}`);
+      renderTrends(await r.json());
+      trendsLoaded = true;
+    } catch (e) { console.error("trends load failed", e); box.textContent = "(trends unavailable)"; }
+  }
+};
+
+function sparkline(runs) {
+  if (!runs.length) return "";
+  const w = 8 * runs.length + 4, h = 24;
+  if (runs.length === 1) {
+    const cx = 4, cy = h - 2 - (runs[0].grade.pct / 100) * (h - 4);
+    return `<svg width="${w}" height="${h}" class="spark"><circle cx="${cx}" cy="${cy}" r="2" fill="currentColor"/></svg>`;
+  }
+  const pts = runs.map((r, i) => `${4 + i * 8},${h - 2 - (r.grade.pct / 100) * (h - 4)}`).join(" ");
+  return `<svg width="${w}" height="${h}" class="spark"><polyline points="${pts}" fill="none" stroke="currentColor" stroke-width="1.5"/></svg>`;
+}
+
+function renderTrends(data) {
+  const box = document.getElementById("trends");
+  if (!data.models.length) { box.innerHTML = `<div class="empty-state">No runs yet.</div>`; return; }
+  const glyph = { PASS: "✓", FAIL: "✗", ERROR: "!" };
+  let html = "";
+  for (const m of data.models) {
+    const last = m.runs[m.runs.length - 1].grade;
+    const badge = last.ship ? "<span class='badge ship'>SHIP</span>" : "<span class='badge no'>NOT READY</span>";
+    const trunc = m.truncated ? ` <span class='dim'>(last ${m.runs.length})</span>` : "";
+    const skippedNote = m.skipped > 0 ? ` <span class='dim'>(${m.skipped} unreadable)</span>` : "";
+    html += `<div class="tmodel"><div class="tmodel-h">${escapeHtml(m.model)} — ${sparkline(m.runs)} ${last.letter} (${last.pct}%) ${badge}${trunc}${skippedNote}</div>`;
+    html += "<table class='tgrid'><thead><tr><th></th>";
+    for (const run of m.runs) html += `<th title="${escapeHtml(run.label || run.timestamp)}">${escapeHtml((run.label || run.timestamp).slice(0, 8))}</th>`;
+    html += "</tr></thead><tbody>";
+    for (const scn of data.scenarios) {
+      html += `<tr><td class='tscn'>${escapeHtml(scn.id)}</td>`;
+      for (const run of m.runs) {
+        const cell = run.cells[scn.id];
+        if (!cell) { html += `<td class='tc absent'>·</td>`; continue; }
+        const g = cell.suspect ? "?" : (glyph[cell.verdict] || "?");
+        const cls = escapeHtml(cell.suspect ? "suspect" : cell.verdict);
+        const title = `${run.label || run.timestamp}${cell.flakiness != null ? ` · flaky ${cell.flakiness.toFixed(2)}` : ""}`;
+        html += `<td class='tc ${cls}' title="${escapeHtml(title)}">${g}</td>`;
+      }
+      html += "</tr>";
+    }
+    html += "</tbody></table></div>";
+  }
+  box.innerHTML = html;
+}
+
+render();
+</script>
+</body>
+</html>

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { type HarnessAdapter } from "@skill-harness/core";
+export interface Args {
+    _: string[];
+    flags: Record<string, string | true>;
+    multi: Record<string, string[]>;
+}
+export declare function flagStr(args: Args, key: string, fallback?: string): string | undefined;
+/** Parse the run's reps + pass-threshold flags. Throws on an invalid provided value. */
+export declare function parseRunTuning(args: Args): {
+    reps: number;
+    passThreshold: number;
+};
+export declare function cmdGrade(args: Args, adapterOverride?: HarnessAdapter): Promise<void>;
+/** Exit-code contract: 0 = clean (no findings), 1 = >=1 finding, or a resolution error (unknown skill/root, no skills with a spec). */
+export declare function cmdLint(args: Args): Promise<void>;
+export declare function main(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import yaml from "js-yaml";
+import { discover, resolveSkill, loadSpec, parseSpec, parseModelRef, runSkillModel, formatScorecard, readResults, regradeRun, lintSkill, } from "@skill-harness/core";
+import { getAdapter } from "@skill-harness/adapters";
+import { serveReview } from "./serve.js";
+const DEFAULT_MODEL = "fireworks:accounts/fireworks/models/deepseek-v4-pro";
+const DEFAULT_JUDGE = "anthropic:claude-opus-4-8";
+const REPEATABLE = new Set(["model", "turn", "check"]);
+function parseArgs(argv) {
+    const _ = [];
+    const flags = {};
+    const multi = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            let key = a.slice(2);
+            let val = true;
+            const eq = key.indexOf("=");
+            if (eq >= 0) {
+                val = key.slice(eq + 1);
+                key = key.slice(0, eq);
+            }
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+                val = argv[++i];
+            }
+            if (REPEATABLE.has(key)) {
+                (multi[key] ??= []).push(val === true ? "" : val);
+            }
+            else {
+                flags[key] = val;
+            }
+        }
+        else {
+            _.push(a);
+        }
+    }
+    return { _, flags, multi };
+}
+export function flagStr(args, key, fallback) {
+    const v = args.flags[key];
+    if (typeof v === "string")
+        return v;
+    if (v === true)
+        return "";
+    return fallback;
+}
+function resolveModels(args) {
+    const models = [...(args.multi.model ?? [])];
+    const file = flagStr(args, "models");
+    if (file) {
+        const text = readFileSync(file, "utf8");
+        for (const line of text.split("\n")) {
+            const t = line.trim();
+            if (t && !t.startsWith("#"))
+                models.push(t);
+        }
+    }
+    // comma-splitting within a single --model token
+    const expanded = models.flatMap((m) => m.split(",").map((s) => s.trim()).filter(Boolean));
+    return expanded.length ? expanded : [DEFAULT_MODEL];
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Parse the run's reps + pass-threshold flags. Throws on an invalid provided value. */
+export function parseRunTuning(args) {
+    let reps = 1;
+    const repsRaw = flagStr(args, "reps");
+    if (repsRaw !== undefined && repsRaw !== "") {
+        const n = Number(repsRaw);
+        if (!Number.isInteger(n) || n < 1)
+            throw new Error(`--reps must be a positive integer (got \`${repsRaw}\`)`);
+        reps = n;
+    }
+    let passThreshold = 0.5;
+    const ptRaw = flagStr(args, "pass-threshold");
+    if (ptRaw !== undefined && ptRaw !== "") {
+        const t = Number(ptRaw);
+        if (!Number.isFinite(t) || t < 0 || t > 1)
+            throw new Error(`--pass-threshold must be a number in [0, 1] (got \`${ptRaw}\`)`);
+        passThreshold = t;
+    }
+    return { reps, passThreshold };
+}
+// ---------------------------------------------------------------- commands
+async function cmdList(args) {
+    const root = flagStr(args, "skills", process.cwd());
+    const skills = discover(root);
+    console.log(`skills under ${root}:`);
+    for (const s of skills) {
+        if (!s.hasSpec) {
+            console.log(`  ○ ${s.name}  (no spec)`);
+            continue;
+        }
+        try {
+            const spec = loadSpec(s.specPath);
+            const seeded = spec.scenarios.filter((x) => x.mode === "seeded").length;
+            const seededNote = seeded ? `, ${seeded} seeded` : "";
+            console.log(`  ● ${s.name}  (${spec.scenarios.length} scenarios${seededNote})`);
+        }
+        catch (e) {
+            console.log(`  ✗ ${s.name}  INVALID: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+    console.log(`\n● = testable · ○ = no spec yet · ✗ = spec present but invalid`);
+}
+async function cmdRun(args) {
+    const root = flagStr(args, "skills", process.cwd());
+    const target = args._[0];
+    if (!target)
+        throw new Error("usage: skill-harness run <skill|all> --skills <root>");
+    const harnessName = flagStr(args, "harness", "pi");
+    const adapter = getAdapter(harnessName);
+    if (!(await adapter.available()))
+        throw new Error(`harness \`${harnessName}\` is not on PATH`);
+    const mode = flagStr(args, "mode", "green") || "green";
+    const judge = parseModelRef(flagStr(args, "judge", DEFAULT_JUDGE));
+    const label = flagStr(args, "label") || null;
+    const parallel = Math.max(1, Number(flagStr(args, "parallel", "1")) || 1);
+    const { reps, passThreshold } = parseRunTuning(args);
+    const modelTokens = resolveModels(args);
+    const skills = target === "all"
+        ? discover(root).filter((s) => s.hasSpec)
+        : [resolveSkill(root, target)];
+    const summaries = [];
+    for (const skill of skills) {
+        if (!skill.hasSpec) {
+            console.log(`skip ${skill.name}: no spec`);
+            continue;
+        }
+        const spec = loadSpec(skill.specPath);
+        for (const token of modelTokens) {
+            const model = parseModelRef(token);
+            console.log(`\n▶ ${spec.skill} · ${harnessName}:${token} · mode=${mode} · judge=${judge.provider}:${judge.model}`);
+            const summary = await runSkillModel({
+                spec,
+                skillDir: skill.dir,
+                specPath: skill.specPath,
+                adapter,
+                model,
+                modelToken: token,
+                judge,
+                mode,
+                timestamp: nowIso(),
+                label,
+                concurrency: parallel,
+                reps,
+                passThreshold,
+                onProgress: (m) => console.log(m),
+            });
+            summaries.push(summary);
+            console.log("\n" + formatScorecard(summary) + "\n");
+        }
+    }
+    console.log(`\nReview interactively:  skill-harness review ${skills[0]?.name ?? "<skill>"} --skills ${root}`);
+}
+export async function cmdGrade(args, adapterOverride) {
+    const runDir = args._[0];
+    if (!runDir || !existsSync(runDir))
+        throw new Error("usage: skill-harness grade <run-dir> [--judge prov:model]");
+    // spec lives at <runDir>/../../../specification.yaml  (results/<tag>/<ts> -> tests/)
+    const testsDir = dirname(dirname(dirname(runDir)));
+    const specPath = join(testsDir, "specification.yaml");
+    const spec = loadSpec(specPath);
+    const prev = existsSync(join(runDir, "results.yaml")) ? readResults(runDir) : null;
+    // Re-judge with the run's RECORDED judge + harness (parity with /rejudge) —
+    // an explicit --judge flag still wins; with no prior results, fall back to
+    // the CLI default.
+    const judgeFlag = flagStr(args, "judge");
+    const judge = judgeFlag ? parseModelRef(judgeFlag) : (prev?.judge ?? parseModelRef(DEFAULT_JUDGE));
+    const adapter = adapterOverride ?? getAdapter(prev?.harness ?? "pi");
+    const results = await regradeRun({ runDir, spec, adapter, judge, specDir: testsDir, now: nowIso });
+    for (const s of results.scenarios) {
+        console.log(`  ${s.id} → ${s.judge_verdict}: ${s.judge_reason}`);
+    }
+    const g = results.effective_grade;
+    console.log(`\n  re-graded with ${judge.provider}:${judge.model} → ${g.letter} (${g.pct}%) ${g.ship ? "SHIP" : "NOT READY"}`);
+}
+async function cmdReview(args) {
+    const root = flagStr(args, "skills", process.cwd());
+    const target = args._[0];
+    if (!target)
+        throw new Error("usage: skill-harness review <skill> --skills <root>");
+    const skill = resolveSkill(root, target);
+    const port = Number(flagStr(args, "port", "0")) || 0;
+    await serveReview({ skillDir: skill.dir, skillName: skill.name, port });
+}
+async function cmdAddTest(args) {
+    const root = flagStr(args, "skills", process.cwd());
+    const target = args._[0];
+    if (!target)
+        throw new Error("usage: skill-harness add-test <skill> --skills <root> --id ... --title ... --turn ... --check ...");
+    const skill = resolveSkill(root, target);
+    if (!skill.hasSpec)
+        throw new Error(`${target} has no spec yet — create tests/specification.yaml first`);
+    const id = flagStr(args, "id");
+    const title = flagStr(args, "title");
+    const turns = args.multi.turn ?? [];
+    const checks = args.multi.check ?? [];
+    if (!id || !title || turns.length === 0 || checks.length === 0) {
+        throw new Error("add-test requires --id, --title, at least one --turn and one --check");
+    }
+    // Validate the merged spec before writing.
+    const existing = loadSpec(skill.specPath);
+    if (existing.scenarios.some((s) => s.id === id))
+        throw new Error(`scenario id \`${id}\` already exists`);
+    const scenario = { id, title };
+    if (flagStr(args, "critical") !== undefined)
+        scenario.critical = true;
+    const mode = flagStr(args, "mode");
+    if (mode === "seeded") {
+        scenario.mode = "seeded";
+        scenario.fixture = flagStr(args, "fixture") ?? `fixtures/${id}`;
+    }
+    scenario.turns = turns;
+    scenario.checklist = checks;
+    const block = "\n" + yaml.dump({ scenarios: [scenario] }).replace(/^scenarios:\n/, "");
+    const merged = readFileSync(skill.specPath, "utf8") + block;
+    parseSpec(merged, skill.specPath); // throws if the append broke the spec
+    appendFileSync(skill.specPath, block, "utf8");
+    console.log(`added scenario ${id} to ${skill.specPath}`);
+}
+/** Exit-code contract: 0 = clean (no findings), 1 = >=1 finding, or a resolution error (unknown skill/root, no skills with a spec). */
+export async function cmdLint(args) {
+    const root = flagStr(args, "skills", process.cwd());
+    const target = args._[0] ?? "all";
+    let skillDirs;
+    try {
+        skillDirs = target === "all"
+            ? discover(root).filter((s) => s.hasSpec).map((s) => s.dir)
+            : [resolveSkill(root, target).dir];
+    }
+    catch (e) {
+        console.error(`error: ${e instanceof Error ? e.message : e}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (skillDirs.length === 0) {
+        console.error(`no skills with a spec under ${root}`);
+        process.exitCode = 1;
+        return;
+    }
+    const gha = process.env.GITHUB_ACTIONS === "true";
+    const findings = [];
+    for (const dir of skillDirs) {
+        let f;
+        try {
+            f = lintSkill(dir);
+        }
+        catch (e) {
+            f = [{ skill: dir, code: "lint-error", message: e instanceof Error ? e.message : String(e) }];
+        }
+        findings.push(...f);
+        if (f.length === 0)
+            console.log(`✓ ${dir}`);
+        else
+            for (const x of f) {
+                const where = x.scenario ? `${dir}/${x.scenario}` : dir; // dir-based label, consistent with the ✓ line
+                console.log(`✗ ${where}: ${x.code} — ${x.message}`);
+                if (gha)
+                    console.log(`::error title=skill-harness::${where}: ${x.code} — ${x.message}`);
+            }
+    }
+    console.log(`\n${skillDirs.length} skill(s), ${findings.length} finding(s)`);
+    process.exitCode = findings.length > 0 ? 1 : 0;
+}
+// ---------------------------------------------------------------- dispatch
+const HELP = `skill-harness — test/optimize loop for agent skills (pi harness)
+
+  run    <skill|all> --skills <root> [--model prov:model ...] [--models file]
+                     [--mode red|green|force] [--judge prov:model] [--harness pi] [--label name] [--parallel N] [--reps N] [--pass-threshold T]
+  grade  <run-dir>   [--judge prov:model]      re-grade saved transcripts (neutral judge)
+  review <skill>     --skills <root> [--port N] serve the interactive review UI
+  add-test <skill>   --skills <root> --id ID --title T --turn ... --check ... [--critical] [--mode seeded --fixture path]
+  list   --skills <root>                        discovered skills + spec status
+  lint   <skill|all> --skills <root>           validate specs/fixtures + results-consistency (CI gate; exits non-zero on findings)
+
+defaults: model=${DEFAULT_MODEL}  judge=${DEFAULT_JUDGE}  mode=green  harness=pi`;
+export async function main(argv) {
+    const cmd = argv[0];
+    const args = parseArgs(argv.slice(1));
+    switch (cmd) {
+        case "run": return cmdRun(args);
+        case "grade": return cmdGrade(args);
+        case "review": return cmdReview(args);
+        case "add-test": return cmdAddTest(args);
+        case "list": return cmdList(args);
+        case "lint": return cmdLint(args);
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            return;
+        default:
+            console.error(`unknown command: ${cmd}\n`);
+            console.log(HELP);
+            process.exitCode = 1;
+    }
+}
+// Skip dispatch under vitest: importing this module (e.g. to exercise cmdGrade
+// directly in tests) must not also run a CLI command against the test runner's
+// own argv. Real entrypoints (tsx on src/cli.ts, or the bin launcher importing
+// dist/cli.js) never set VITEST, so this leaves production invocation untouched.
+if (!process.env.VITEST) {
+    main(process.argv.slice(2)).catch((e) => {
+        console.error(`error: ${e instanceof Error ? e.message : e}`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/serve.d.ts

@@ -0,0 +1,14 @@
+export interface ServeOptions {
+    skillDir: string;
+    skillName: string;
+    port?: number;
+    open?: boolean;
+    adapter?: import("@skill-harness/core").HarnessAdapter;
+    assetsDir?: string;
+}
+export interface ServeHandle {
+    port: number;
+    close: () => void;
+}
+export declare function serveReview(opts: ServeOptions): Promise<ServeHandle>;
+export declare function tryOpen(url: string, cmd?: string): void;

package/dist/serve.js

@@ -0,0 +1,222 @@
+import { createServer } from "node:http";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { collectReport, renderReport, collectTrends, readResults, writeResults, applyOverride, preserveTranscript, findTranscriptFiles, ensureResultsGitignore, appendJournal, loadSpec, regradeScenario, findJudgeRawFiles, effectiveThreshold, } from "@skill-harness/core";
+import { getAdapter } from "@skill-harness/adapters";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Locate assets/report.template.html relative to dist/ or src/. */
+function templatePath(assetsDir) {
+    if (assetsDir)
+        return join(assetsDir, "report.template.html");
+    const candidates = [
+        join(__dirname, "..", "..", "..", "assets", "report.template.html"), // packages/cli/{dist,src} -> ../../../assets
+        join(__dirname, "..", "assets", "report.template.html"),
+        join(__dirname, "..", "..", "assets", "report.template.html"),
+    ];
+    for (const c of candidates)
+        if (existsSync(c))
+            return c;
+    throw new Error("cannot find assets/report.template.html");
+}
+/** assets/report.grade.js — the client scorer injected into the template (sibling of the template). */
+function gradeScriptPath(assetsDir) {
+    return join(dirname(templatePath(assetsDir)), "report.grade.js");
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let b = "";
+        req.on("data", (c) => (b += c));
+        req.on("end", () => resolve(b));
+    });
+}
+/** All of a scenario's transcripts, concatenated with a filename header per file for reps runs. */
+function findTranscript(runDir, id) {
+    const files = findTranscriptFiles(runDir, id);
+    if (files.length === 0)
+        return null;
+    if (files.length === 1)
+        return readFileSync(join(runDir, files[0]), "utf8");
+    return files.map((f) => `===== ${f} =====\n${readFileSync(join(runDir, f), "utf8")}`).join("\n\n");
+}
+/** All of a scenario's judge-raw artifacts, concatenated with a header per rep. */
+function findJudgeRaw(runDir, id) {
+    // Mode-agnostic (no mode arg): run.ts writes judge-raw for every mode
+    // (red/force too), and /transcript's findTranscript is mode-agnostic —
+    // the inspector must show a red/force run's judge output too.
+    const files = findJudgeRawFiles(runDir, id);
+    if (files.length === 0)
+        return null;
+    if (files.length === 1)
+        return readFileSync(join(runDir, files[0]), "utf8");
+    return files.map((f) => `===== ${f} =====\n${readFileSync(join(runDir, f), "utf8")}`).join("\n\n");
+}
+export async function serveReview(opts) {
+    const template = readFileSync(templatePath(opts.assetsDir), "utf8");
+    const gradeScript = readFileSync(gradeScriptPath(opts.assetsDir), "utf8");
+    const server = createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (req.method === "GET" && url.pathname === "/") {
+                const data = collectReport(opts.skillDir);
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end(renderReport(template, data, gradeScript));
+                return;
+            }
+            if (req.method === "GET" && url.pathname === "/transcript") {
+                const col = Number(url.searchParams.get("col"));
+                const id = url.searchParams.get("id") ?? "";
+                const data = collectReport(opts.skillDir);
+                const column = data.columns.find((c) => c.index === col);
+                const text = column ? findTranscript(column.runDir, id) : null;
+                res.writeHead(text ? 200 : 404, { "content-type": "text/plain; charset=utf-8" });
+                res.end(text ?? "transcript not found");
+                return;
+            }
+            if (req.method === "GET" && url.pathname === "/judge") {
+                const col = Number(url.searchParams.get("col"));
+                const id = url.searchParams.get("id") ?? "";
+                const data = collectReport(opts.skillDir);
+                const column = data.columns.find((c) => c.index === col);
+                const text = column ? findJudgeRaw(column.runDir, id) : null;
+                res.writeHead(text ? 200 : 404, { "content-type": "text/plain; charset=utf-8" });
+                res.end(text ?? "judge output not captured");
+                return;
+            }
+            if (req.method === "GET" && url.pathname === "/trends") {
+                const data = collectTrends(opts.skillDir);
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify(data));
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/rejudge") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const data = collectReport(opts.skillDir);
+                const column = data.columns.find((c) => c.index === body.col);
+                if (!column) {
+                    res.writeHead(404).end("unknown column");
+                    return;
+                }
+                const results = readResults(column.runDir);
+                if (results.mode !== "green") {
+                    res.writeHead(400, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ ok: false, error: "only green runs can be re-judged" }));
+                    return;
+                }
+                const specPath = join(opts.skillDir, "tests", "specification.yaml");
+                const spec = loadSpec(specPath);
+                const scenario = spec.scenarios.find((s) => s.id === body.scenarioId);
+                if (!scenario) {
+                    res.writeHead(404).end("unknown scenario");
+                    return;
+                }
+                const adapter = opts.adapter ?? getAdapter(results.harness);
+                if (!(await adapter.available())) {
+                    res.writeHead(400, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ ok: false, error: `harness \`${results.harness}\` is not on PATH` }));
+                    return;
+                }
+                const prev = results.scenarios.find((s) => s.id === body.scenarioId);
+                if (!prev) {
+                    res.writeHead(404).end("scenario not in this run");
+                    return;
+                }
+                const threshold = effectiveThreshold(prev, scenario);
+                try {
+                    const rr = await regradeScenario({
+                        runDir: column.runDir, spec, scenario, adapter, judge: results.judge,
+                        specDir: dirname(specPath), threshold,
+                    });
+                    const merged = results.scenarios.map((s) => s.id === body.scenarioId ? { ...rr, override: s.override, note: s.note } : s);
+                    const written = writeResults(column.runDir, {
+                        skill: results.skill, harness: results.harness, model: results.model, judge: results.judge,
+                        timestamp: results.timestamp, label: results.label, mode: results.mode, scenarios: merged,
+                    }, { shipBar: spec.ship_bar, critical: spec.critical });
+                    ensureResultsGitignore(join(opts.skillDir, "tests", "results"));
+                    const g = written.effective_grade;
+                    appendJournal(column.runDir, { event: "score", ts: new Date().toISOString(), passed: g.passed, total: g.total, pct: g.pct, letter: g.letter, ship: g.ship, note: g.note });
+                    res.writeHead(200, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ ok: true, grade: g }));
+                }
+                catch (e) {
+                    // regradeScenario (or the write/journal that follows) failed — surface the
+                    // real reason as JSON so the client's r.json().catch(()=>({})) sees body.error
+                    // instead of falling through to the generic top-level 500 (text/plain).
+                    res.writeHead(400, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+                }
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/save") {
+                const body = JSON.parse((await readBody(req)) || "{}");
+                const data = collectReport(opts.skillDir);
+                const column = data.columns.find((c) => c.index === body.col);
+                if (!column) {
+                    res.writeHead(404).end("unknown column");
+                    return;
+                }
+                const results = readResults(column.runDir);
+                let patched;
+                try {
+                    patched = applyOverride(results, body.scenarioId, body.override ?? null, body.note ?? "");
+                }
+                catch (e) {
+                    res.writeHead(400, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+                    return;
+                }
+                // writeResults recomputes effective_grade override-aware against the CURRENT
+                // spec's ship bar — a saved override can never leave a stale grade. Only
+                // green runs are scored (PR #1 finding: /save must not grade red/force runs).
+                const spec = loadSpec(join(opts.skillDir, "tests", "specification.yaml"));
+                const ctx = patched.mode === "green" ? { shipBar: spec.ship_bar, critical: spec.critical } : null;
+                writeResults(column.runDir, patched, ctx);
+                // Unconditional: a results root created before schema-2/journal.jsonl existed
+                // may still have a stale .gitignore body — every save (not just overrides)
+                // must roll it forward so journal.jsonl doesn't end up tracked.
+                ensureResultsGitignore(join(opts.skillDir, "tests", "results"));
+                if (body.override != null) {
+                    preserveTranscript(join(opts.skillDir, "tests", "results"), column.runDir, body.scenarioId);
+                }
+                appendJournal(column.runDir, {
+                    event: "override", ts: new Date().toISOString(),
+                    id: body.scenarioId, override: body.override ?? null, note: body.note ?? "",
+                });
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ ok: true }));
+                return;
+            }
+            res.writeHead(404).end("not found");
+        }
+        catch (e) {
+            res.writeHead(500, { "content-type": "text/plain" });
+            res.end(`server error: ${e instanceof Error ? e.message : e}`);
+        }
+    });
+    await new Promise((resolve) => server.listen(opts.port ?? 0, "127.0.0.1", resolve));
+    const addr = server.address();
+    const port = typeof addr === "object" && addr ? addr.port : opts.port;
+    const link = `http://127.0.0.1:${port}/`;
+    console.log(`\n  skill-harness review · ${opts.skillName}`);
+    console.log(`  → ${link}`);
+    console.log(`  flip verdicts + add notes in the browser; saves persist to results.yaml.`);
+    console.log(`  Ctrl-C to stop.\n`);
+    if (opts.open !== false && !process.env.SKILL_CHECK_NO_OPEN)
+        tryOpen(link);
+    return { port: port, close: () => server.close() };
+}
+export function tryOpen(url, cmd) {
+    const opener = cmd ?? (process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open");
+    try {
+        const child = spawn(opener, [url], { stdio: "ignore", detached: true });
+        // spawn emits 'error' asynchronously (e.g. xdg-open ENOENT in headless envs);
+        // an unhandled 'error' event would crash the process — swallow it.
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* best effort */
+    }
+}
+//# sourceMappingURL=serve.js.map

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@skill-harness/cli",
+    "version": "0.1.0",
+    "type": "module",
+    "license": "MIT",
+    "main": "./dist/cli.js",
+    "bin": {
+        "skill-harness": "dist/cli.js"
+    },
+    "exports": {
+        ".": "./dist/cli.js",
+        "./serve": "./dist/serve.js"
+    },
+    "files": [
+        "dist/**/*.js",
+        "dist/**/*.d.ts",
+        "assets",
+        "LICENSE"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mojomanyana/skill-harness.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "prepack": "rm -rf ./assets && cp -r ../../assets ./assets && cp ../../LICENSE ./LICENSE"
+    },
+    "dependencies": {
+        "@skill-harness/core": "0.1.0",
+        "@skill-harness/adapters": "0.1.0"
+    }
+}