skalpel 4.0.30 → 4.0.31

package/card.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// card.mjs — THE CATCH CARD: `skalpel card`.
+//
+// THE PROBLEM (same root as verify-shadow / catches): your agent is both the executor AND the reporter
+// of its own work, so when it says "done / tests pass" nothing independent re-checks. verify-shadow
+// already closes that loop LIVE and logs the real verdict. THIS turns a single, already-verified catch
+// into a clean, copy-pasteable artifact you can drop into Slack / a PR / X — so the moment the agent
+// gets caught is shareable, and it's the AGENT that's on the hook, never you.
+//
+// WHAT IT IS: a one-command render of the MOST RECENT genuine catch (a GENUINE_FAIL row) that
+// verify-shadow already wrote to ~/.skalpel/verify-shadow.log. The card carries ONLY what the real row
+// holds: the agent's verbatim completion claim, the exact proof/probe command skalpel re-ran, the real
+// verdict (FAIL — the proof exited non-zero; plus a real exit code / HTTP status / failing-count ONLY
+// when the captured output literally contains one), the verbatim tail of the real output, and the real
+// timestamp. Nothing else — no summaries, no aggregates, no cross-model claims, no minutes.
+//
+// HARD RED LINES (why this is safe + honest):
+//   • READ-ONLY over verify-shadow's OWN output. It only READS ~/.skalpel/verify-shadow.log. It NEVER
+//     re-runs a proof, spawns, builds, writes, deploys, or mutates anything, and opens no socket.
+//   • OPT-IN. User-invoked subcommand; prints and exits. The per-turn hook is untouched (byte-identical
+//     when the shadow is off — this file is never imported by the hook path).
+//   • VERIFIED CATCHES ONLY. It renders a row ONLY if that row is a GENUINE_FAIL (the agent's own
+//     test/build/lint really ran and exited non-zero). A HARNESS_ERROR (timeout / missing-script /
+//     wrong-cwd) is proof-machinery noise, never a catch, and is never rendered — we never cry wolf.
+//   • NO FABRICATED NUMBERS. Every value on the card traces to a real field of the real row. The banned
+//     "minutes saved / lost" metric never appears. An exit code / HTTP status / failing count is shown
+//     ONLY when the row's own captured output literally contains it. If there is no catch to show, it
+//     SAYS so honestly — it never invents one.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { VERIFY_LOG_PATH, extractFailCount } from "./verify-shadow.mjs";
+
+// Bound the read so a pathological log can never OOM us (verify-shadow already trims to ~1MB/500 lines).
+const MAX_LOG_BYTES = 4 * 1024 * 1024;
+
+// ---------- palette (matches the statusline / setup) ----------
+const R = "\x1b[38;2;233;38;31m"; // skalpel red
+const D = "\x1b[2m";
+const B = "\x1b[1m";
+const X = "\x1b[0m";
+
+// ---------- sanitize (values come from real captured output — strip any control/ANSI bytes) ----------
+// The claim / proof / evidence are captured from the agent's transcript + test output; they must never
+// be able to inject their own escape codes into the terminal or a pasted card. Strip ESC + other C0
+// control chars (keep normal whitespace which we then collapse), and cap length.
+function clean(s, n) {
+  const t = String(s == null ? "" : s)
+    // eslint-disable-next-line no-control-regex
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "") // ANSI CSI sequences
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ") // other control chars → space
+    .replace(/\s+/g, " ")
+    .trim();
+  if (n && t.length > n) return t.slice(0, n - 1) + "…";
+  return t;
+}
+
+// ---------- (1) read + select the catch ----------
+// A row is a genuine catch iff the agent's OWN proof really ran and exited non-zero. verify-shadow
+// records that as outcome==="GENUINE_FAIL" (pass_fail==="FAIL"). HARNESS_ERROR / PASS / no-proof rows
+// are never catches. We tolerate a future "ship-FAIL" label defensively but still exclude harness noise.
+export function isGenuineCatch(row) {
+  if (!row || typeof row !== "object") return false;
+  if (row.outcome === "HARNESS_ERROR" || row.pass_fail === "HARNESS_ERROR") return false;
+  const failed = row.outcome === "GENUINE_FAIL" || row.pass_fail === "FAIL";
+  // A real catch must carry the two things the card indicts the agent with: what it claimed, and the
+  // proof that contradicts it. A row missing either can't be rendered honestly, so it isn't a catch.
+  return failed && !!row.proof_command && !!row.claim_text;
+}
+
+// readCatches() → all genuine-catch rows in the shadow log, oldest→newest as written. Fail-open: any
+// read/parse error yields [] (rendered as the honest "no catches yet" state).
+export function readCatches(logPath = VERIFY_LOG_PATH) {
+  let raw;
+  try {
+    raw = readFileSync(logPath, "utf8");
+  } catch {
+    return [];
+  }
+  if (raw.length > MAX_LOG_BYTES) raw = raw.slice(-MAX_LOG_BYTES);
+  const out = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue; // partial/garbage line — skip
+    }
+    if (isGenuineCatch(row)) out.push(row);
+  }
+  return out;
+}
+
+// selectCatch({ id }) → the catch to render: the newest overall, or (with --id) the newest for that
+// session id. Returns null when there is nothing genuine to show. `catches` is injectable for tests.
+export function selectCatch({ id = null, catches = null, logPath = VERIFY_LOG_PATH } = {}) {
+  const rows = catches || readCatches(logPath);
+  if (!rows.length) return null;
+  const pool = id ? rows.filter((r) => r.session === id) : rows;
+  if (!pool.length) return null;
+  return pool[pool.length - 1]; // rows are append-ordered → last is newest
+}
+
+// ---------- (2) honest verdict extraction ----------
+// A GENUINE_FAIL means, by verify-shadow's own classifyOutcome, that the proof PROCESS exited non-zero
+// (not a timeout, not command-not-found, not a missing script — those are HARNESS_ERROR). So
+// "exited non-zero" is always provably true for a catch row. Beyond that, we surface a SPECIFIC code
+// ONLY when the real captured output literally printed one — never invented.
+export function extractCode(evidence) {
+  const s = String(evidence || "");
+  // HTTP status first (auth/proxy/API proofs surface these): "HTTP/1.1 500", "status: 503",
+  // "responded with 429", "got 401". Only 1xx–5xx are treated as a status.
+  const http = s.match(
+    /\b(?:HTTP\/\d(?:\.\d)?\s+|status(?:\s+code)?[:\s]+|responded with\s+|returned\s+|got\s+)(\d{3})\b/i,
+  );
+  if (http) {
+    const n = Number.parseInt(http[1], 10);
+    if (n >= 100 && n < 600) return { kind: "http", value: n };
+  }
+  // Process exit code: "exit code 1", "exited with code 2", "Process exited with code 1".
+  const exit = s.match(/exit(?:ed)?(?:\s+with)?\s+(?:code\s+)?(\d{1,3})\b/i);
+  if (exit) {
+    const n = Number.parseInt(exit[1], 10);
+    if (Number.isFinite(n)) return { kind: "exit", value: n };
+  }
+  return null;
+}
+
+// verdictPhrase(row) → the honest one-line verdict. Always truthful for a catch row.
+function verdictPhrase(row) {
+  const code = extractCode(row.evidence);
+  const failN = extractFailCount(row.evidence);
+  const count = failN != null ? ` · ${failN} failing` : "";
+  if (code && code.kind === "http") return `FAIL — its own proof got HTTP ${code.value}${count}`;
+  if (code && code.kind === "exit") return `FAIL — its own proof exited ${code.value}${count}`;
+  return `FAIL — its own proof re-ran and exited non-zero${count}`;
+}
+
+// Human timestamp: keep the real ISO instant (never fabricated); show it verbatim.
+function stamp(ts) {
+  const s = clean(ts, 40);
+  return s || "unknown time";
+}
+
+// ---------- (3a) plain-text card (no ANSI — the shareable artifact) ----------
+export function renderPlainCard(row) {
+  const claim = clean(row.claim_text, 200) || "it's done";
+  const proof = clean(row.proof_command, 200) || "its own proof";
+  const evidence = clean(row.evidence, 200);
+  const L = [];
+  L.push("🔬 skalpel — verified catch");
+  L.push("");
+  L.push("The agent claimed:");
+  L.push(`  "${claim}"`);
+  L.push("");
+  L.push("skalpel re-ran the agent's OWN proof, out-of-band:");
+  L.push(`  $ ${proof}`);
+  L.push(`  → ${verdictPhrase(row)}`);
+  if (evidence) {
+    L.push("");
+    L.push("real output (verbatim):");
+    L.push(`  ${evidence}`);
+  }
+  L.push("");
+  L.push(`caught ${stamp(row.ts)}`);
+  L.push("The agent said done. Its own proof, re-run, disagreed.");
+  return L.join("\n");
+}
+
+// ---------- (3b) markdown card (Slack / PR / X) ----------
+export function renderMarkdownCard(row) {
+  const claim = clean(row.claim_text, 200) || "it's done";
+  const proof = clean(row.proof_command, 200) || "its own proof";
+  const evidence = clean(row.evidence, 200);
+  const FENCE = "```";
+  const L = [];
+  L.push("**🔬 skalpel — verified catch**");
+  L.push("");
+  L.push(`> The agent claimed: _"${claim}"_`);
+  L.push("");
+  L.push("skalpel re-ran the agent's own proof, out-of-band:");
+  L.push(FENCE);
+  L.push(`$ ${proof}`);
+  L.push(`→ ${verdictPhrase(row)}`);
+  L.push(FENCE);
+  if (evidence) {
+    L.push("real output (verbatim):");
+    L.push(FENCE);
+    L.push(evidence);
+    L.push(FENCE);
+  }
+  L.push(`_Caught ${stamp(row.ts)}. The agent said done; its own proof, re-run, disagreed._`);
+  return L.join("\n");
+}
+
+// ---------- (3c) styled terminal card ----------
+function renderTerminalCard(row) {
+  const claim = clean(row.claim_text, 200) || "it's done";
+  const proof = clean(row.proof_command, 200) || "its own proof";
+  const evidence = clean(row.evidence, 180);
+  const L = [];
+  L.push("");
+  L.push(`  ${B}🔬 skalpel${X} ${D}·${X} ${B}${R}verified catch${X}`);
+  L.push(`  ${D}${"─".repeat(70)}${X}`);
+  L.push(`  ${D}The agent claimed:${X}`);
+  L.push(`    ${B}"${claim}"${X}`);
+  L.push("");
+  L.push(`  ${D}skalpel re-ran the agent's OWN proof, out-of-band:${X}`);
+  L.push(`    ${D}$${X} ${proof}`);
+  L.push(`    ${R}${B}→ ${verdictPhrase(row)}${X}`);
+  if (evidence) {
+    L.push("");
+    L.push(`  ${D}real output:${X} ${evidence}`);
+  }
+  L.push(`  ${D}${"─".repeat(70)}${X}`);
+  L.push(
+    `  ${D}caught ${stamp(row.ts)} — the agent said done; its own proof, re-run, disagreed.${X}`,
+  );
+  L.push("");
+  return L.join("\n");
+}
+
+// ---------- (4) the honest empty state ----------
+function renderNoCatch({ id }) {
+  const L = [];
+  L.push("");
+  L.push(`  ${B}🔬 skalpel card${X}`);
+  L.push(`  ${D}${"─".repeat(70)}${X}`);
+  if (id) {
+    L.push(`  ${D}No verified catch found for session ${clean(id, 60)}.${X}`);
+  } else {
+    L.push(`  ${D}No verified catch to show yet.${X}`);
+  }
+  L.push("");
+  L.push(
+    `  ${D}A card is minted only from a REAL catch — a turn where your agent claimed "done"${X}`,
+  );
+  L.push(
+    `  ${D}and skalpel re-ran its OWN proof and it genuinely FAILED. Nothing is invented.${X}`,
+  );
+  L.push("");
+  L.push(
+    `  ${D}Turn the live shadow on with ${X}${B}SKALPEL_VERIFY_SHADOW=1${X}${D}, keep coding, and${X}`,
+  );
+  L.push(`  ${D}run ${X}${B}skalpel card${X}${D} again the next time a claim doesn't hold up.${X}`);
+  L.push("");
+  return L.join("\n");
+}
+
+// ---------- (5) top-level render (used by CLI + tests) ----------
+// format ∈ { "terminal" (default), "md", "plain" }. Returns the string to print. `catches` injectable.
+export function renderCard({ id = null, format = "terminal", catches = null } = {}) {
+  const row = selectCatch({ id, catches });
+  if (!row) return renderNoCatch({ id });
+  if (format === "md") return renderMarkdownCard(row);
+  if (format === "plain") return renderPlainCard(row);
+  // Default terminal view = the styled card, followed by a copy-pasteable markdown block for sharing.
+  return (
+    renderTerminalCard(row) +
+    "\n" +
+    `  ${D}copy for Slack / a PR / X ${X}${D}(or: ${X}${B}skalpel card --md | pbcopy${X}${D}):${X}\n\n` +
+    renderMarkdownCard(row) +
+    "\n"
+  );
+}
+
+// ---------- CLI ----------
+function parseArgs(argv) {
+  let id = null;
+  let format = "terminal";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--last")
+      continue; // newest catch (the default) — accepted for explicitness
+    else if (a === "--id") {
+      id = argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[++i] : null;
+    } else if (a.startsWith("--id=")) id = a.slice("--id=".length);
+    else if (a === "--md" || a === "--markdown") format = "md";
+    else if (a === "--plain" || a === "--text") format = "plain";
+  }
+  return { id, format };
+}
+
+const isMain = (() => {
+  try {
+    return (
+      Boolean(process.argv[1]) &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  try {
+    const { id, format } = parseArgs(process.argv.slice(2));
+    process.stdout.write(renderCard({ id, format }) + "\n");
+  } catch {
+    // READ-ONLY + fail-open: never throw at the user.
+    process.stdout.write("\n  🔬 skalpel — could not read your catch log on this machine.\n\n");
+  }
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.30",
+  "version": "4.0.31",
   "description": "Behavioral graph for AI-assisted coding — learns how you work and steers Claude Code + Codex in real time.",
   "type": "module",
   "bin": {

package/skalpel-setup.mjs

@@ -62,6 +62,7 @@ const KNOWN_SUBS = new Set([
   "autopsy",
   "xray",
   "catches",
+  "card",
   "__build",
   "__verify-report",
 ]);
@@ -77,6 +78,7 @@ usage:
   skalpel autopsy                               local, read-only receipt of your verified patterns
   skalpel xray                                  re-run your last session's own proof — did "done" hold up?
   skalpel catches                               scan your own history for "done" claims over failing tests
+  skalpel card [--last|--id <id>] [--md]        share one verified catch: the claim + its own failing proof
   skalpel uninstall [--purge]                   remove the hooks + local data from this machine
 
 options:
@@ -112,6 +114,11 @@ function validateArgv() {
       process.exit(0);
     }
     if (BOOL_FLAGS.has(a)) continue; // valueless flag (e.g. `uninstall --purge`)
+    // `skalpel card` owns its own flags (--last / --id <id> / --md / --plain) and forwards them to
+    // card.mjs. They are NOT setup options, so setup must not reject them as unknown — pass any token
+    // after the `card` subcommand straight through (card.mjs validates its own flags). Global -v/-h
+    // above still win for a bare `skalpel -v`. Scoped to `card` so no other subcommand's contract shifts.
+    if (i > 0 && argv[0] === "card") continue;
     if (a.startsWith("-")) {
       console.error(`skalpel: unknown option \`${a}\`\n\n${USAGE}`);
       process.exit(2);
@@ -878,6 +885,17 @@ async function main() {
     spawnSync("node", [join(__dir, "catches.mjs"), ...argv.slice(1)], { stdio: "inherit" });
     return;
   }
+  // `skalpel card` — THE CATCH CARD: a LOCAL, READ-ONLY, ZERO-NETWORK render of ONE already-verified
+  // catch that the live shadow (verify-shadow) wrote to ~/.skalpel/verify-shadow.log — the agent's
+  // verbatim "done" claim, the exact proof command skalpel re-ran, the real FAIL verdict, and the
+  // verbatim output tail — as a clean, copy-pasteable card for Slack / a PR / X. It never re-runs a
+  // proof, never touches the network; renders only a GENUINE_FAIL row (never harness noise) and, if
+  // there's no catch to show, says so honestly. `--md`/`--plain` pick the export; `--id <session>`
+  // targets a specific session; `--last` (default) is the newest catch.
+  if (sub === "card") {
+    spawnSync("node", [join(__dir, "card.mjs"), ...argv.slice(1)], { stdio: "inherit" });
+    return;
+  }
   // `skalpel __verify-report` — the claim-verification SHADOW instrument: reads the local
   // verify-shadow.log and prints the three numbers (claim fire-rate, proof-reconstruction rate, and the
   // headline MISMATCH rate = how often the agent claimed done but its OWN proof, re-run, failed).