skalpel 4.0.31 → 4.0.32

package/ledger.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+// ledger.mjs — the PERSONAL TRUTH LEDGER: `skalpel ledger`.
+//
+// THE PROBLEM: your agent is both the executor AND the reporter of its own work. Every "done / tests
+// pass / fixed" it emits is a CLAIM. The claim-verification SHADOW (verify-shadow.mjs) already re-runs
+// the session's OWN proof on each such claim and appends one honest row per claim to
+// ~/.skalpel/verify-shadow.log. That file is already an APPEND-ONLY, LOCAL history of every
+// claim -> verdict. What was missing was a VIEW: the running personal tally of how many "done"s were
+// checked and how many were caught FALSE, with the receipts.
+//
+// THIS is that view. It DERIVES entirely from verify-shadow.log — it NEVER re-runs a proof, NEVER writes
+// a second copy of the history (no double-write), NEVER touches the network, and NEVER touches the
+// per-turn hook. It is a user-invoked, read-only subcommand: opt-in by construction, dark by default,
+// byte-identical to before when not invoked.
+//
+// HARD RED LINES (why this is safe + honest):
+//   • DERIVED, NOT DOUBLE-WRITTEN. The append-only ledger IS verify-shadow.log (written by the shadow).
+//     This module only READS it and renders a view. It writes no ledger file of its own.
+//   • READ-ONLY + LOCAL. Imports only node: core + local sibling modules. Opens no socket. Re-runs nothing
+//     (the pass/fail is the verdict the shadow already recorded).
+//   • NO FABRICATED / ESTIMATED NUMBERS. Every count is a real tally over real logged rows. The ONLY time
+//     figure shown is a MEASURED wall-clock delta between two REAL logged timestamps — the moment a "done"
+//     was caught FALSE (mismatch row) and the moment that SAME proof, in that SAME session, was later
+//     logged PASS. If no such later PASS exists, we show the count ONLY — never an estimate, never a
+//     "minutes saved / lost" tally (that metric stays DEAD).
+//   • FAIL-OPEN. Any read/parse error yields an honest zero-state, never a throw at the user.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+// READ-ONLY reuse of the shadow's single-sourced log path + its honest fail-count extractor. Importing
+// verify-shadow.mjs runs no side effects (its CLI block is guarded on isMain) and modifies nothing there.
+import { VERIFY_LOG_PATH, extractFailCount } from "./verify-shadow.mjs";
+
+// ---------- (1) read the append-only history (verify-shadow.log) ----------
+// One NDJSON row per logged claim:
+//   { ts, session, claim_text, proof_command|null, pass_fail: "PASS"|"FAIL"|"HARNESS_ERROR"|null,
+//     outcome: "PASS"|"GENUINE_FAIL"|"HARNESS_ERROR", mismatch: boolean, evidence }
+// The file is size-capped by the shadow (newest rows kept), so a plain read is safe.
+export function readLedgerRows(path = VERIFY_LOG_PATH) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null; // no shadow log yet → honest zero-state (distinct from "log exists but empty")
+  }
+  const rows = [];
+  for (const line of raw.split("\n")) {
+    const l = line.trim();
+    if (!l) continue;
+    try {
+      const r = JSON.parse(l);
+      if (r && typeof r === "object") rows.push(r);
+    } catch {
+      /* a partial/garbage line — skip it (fail-open) */
+    }
+  }
+  return rows;
+}
+
+// ---------- (2) the MEASURED wall-clock delta (real timestamps only) ----------
+// Parse an ISO timestamp to epoch ms, or null if it isn't a real parseable time.
+function tsMs(ts) {
+  if (typeof ts !== "string") return null;
+  const n = Date.parse(ts);
+  return Number.isFinite(n) ? n : null;
+}
+
+// measureFixDelta(falseRow, rows) → { ms, atTs } for the EARLIEST later row that is, in the SAME session,
+// the SAME proof_command, and a genuine PASS whose timestamp is strictly after the caught-false claim.
+// That is the real moment the false "done" became a true "done": the exact proof that failed later passed.
+// Returns null when no such row exists (then the ledger shows the count only — never an invented minute).
+export function measureFixDelta(falseRow, rows) {
+  const t0 = tsMs(falseRow.ts);
+  if (t0 == null) return null;
+  const session = falseRow.session ?? null;
+  const proof = falseRow.proof_command || null;
+  if (!proof) return null; // can't tie a fix to a claim with no proof — count only
+  let best = null;
+  for (const r of rows) {
+    if (r === falseRow) continue;
+    if ((r.session ?? null) !== session) continue;
+    if ((r.proof_command || null) !== proof) continue;
+    if (r.outcome !== "PASS") continue; // the SAME proof genuinely passing = the real done
+    const t1 = tsMs(r.ts);
+    if (t1 == null || t1 <= t0) continue; // must be strictly LATER than the false claim
+    if (best == null || t1 < best) best = t1;
+  }
+  return best == null ? null : { ms: best - t0, atTs: new Date(best).toISOString() };
+}
+
+// ---------- (3) build the ledger view from the rows ----------
+// verdict per row:
+//   "FALSE"        — mismatch true: claimed done, its OWN proof re-run GENUINELY failed (a caught lie)
+//   "verified"     — pass_fail PASS: claimed done, its OWN proof re-run really passed (a true done)
+//   "unverifiable" — no re-runnable proof, or HARNESS_ERROR (timeout/missing-script/wrong-cwd) — NEVER a lie
+export function buildLedger(rows) {
+  const entries = (rows || []).map((r) => {
+    let verdict;
+    if (r.mismatch === true) verdict = "FALSE";
+    else if (r.pass_fail === "PASS") verdict = "verified";
+    else verdict = "unverifiable";
+    return {
+      ts: r.ts || null,
+      session: r.session ?? null,
+      claim_text: r.claim_text || "",
+      // Ship-status rows (category:"ship") record the check under probe_command, not proof_command —
+      // fall back so a caught ship-lie shows its real probe command, not an empty one.
+      proof_command: r.proof_command || r.probe_command || null,
+      evidence: r.evidence || "",
+      fail_count: extractFailCount(r.evidence),
+      verdict,
+      _row: r,
+    };
+  });
+
+  // "Checked" = claims we got a genuine re-run verdict for (a true PASS or a caught FALSE). Unverifiable
+  // rows (no proof / harness noise) are logged but NOT counted as checked — we can't stand behind them.
+  const checked = entries.filter((e) => e.verdict === "FALSE" || e.verdict === "verified").length;
+  const falseEntries = entries.filter((e) => e.verdict === "FALSE");
+  // Attach the MEASURED fix delta where — and only where — a real later same-proof PASS exists.
+  for (const e of falseEntries) {
+    const d = measureFixDelta(e._row, rows || []);
+    e.fix_delta_ms = d ? d.ms : null;
+    e.fixed_at = d ? d.atTs : null;
+  }
+  return {
+    total: entries.length,
+    checked,
+    falseCount: falseEntries.length,
+    verifiedCount: entries.filter((e) => e.verdict === "verified").length,
+    unverifiableCount: entries.filter((e) => e.verdict === "unverifiable").length,
+    entries,
+    falseEntries,
+  };
+}
+
+// ---------- (4) render ----------
+function clip(s, n) {
+  const t = String(s || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+
+// Format a MEASURED millisecond delta as a human duration. Input is a real (t_pass - t_false) delta; this
+// only formats it — it never rounds up into an invented number. Sub-second deltas read as "<1s".
+export function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return null;
+  const s = Math.floor(ms / 1000);
+  if (s < 1) return "<1s";
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  if (h > 0) return `${h}h ${m}m`;
+  if (m > 0) return `${m}m ${sec}s`;
+  return `${sec}s`;
+}
+
+const MAX_RECEIPTS = 5;
+
+export function renderLedger(ledger, { logPath = VERIFY_LOG_PATH } = {}) {
+  const L = [];
+  L.push("");
+  L.push(
+    '  🔬 skalpel — personal truth ledger (every "done" your agent claimed, checked by its own proof)',
+  );
+  L.push("  " + "─".repeat(74));
+
+  if (ledger == null) {
+    L.push("");
+    L.push("  No claim-verification history yet on this machine.");
+    L.push(
+      "  Enable the shadow with SKALPEL_VERIFY_SHADOW=1, then keep coding — every turn your agent",
+    );
+    L.push('  claims "done / tests pass" gets its own proof re-run and appended to the ledger.');
+    L.push("");
+    return L.join("\n");
+  }
+
+  const { checked, falseCount } = ledger;
+  L.push("");
+  // THE HEADLINE — both numbers are real counts over the real append-only log.
+  L.push(
+    `  ${checked} done-claim${checked === 1 ? "" : "s"} checked, ${falseCount} verified FALSE.`,
+  );
+
+  if (ledger.total === 0) {
+    L.push("");
+    L.push("  The ledger is empty — no completion claims logged yet. I'll append every one live.");
+    L.push("");
+    return L.join("\n");
+  }
+
+  if (falseCount === 0) {
+    L.push("");
+    L.push('  No caught lies — every checked "done" held up against its own proof. Clean ledger.');
+    if (ledger.unverifiableCount > 0) {
+      L.push(
+        `  (${ledger.unverifiableCount} claim(s) logged but unverifiable — no re-runnable proof or harness noise; not counted.)`,
+      );
+    }
+    L.push("");
+    return L.join("\n");
+  }
+
+  L.push("");
+  L.push(
+    "  Every FALSE below is real — the agent's own proof, re-run, did NOT pass at claim time:",
+  );
+  L.push("");
+
+  const top = ledger.falseEntries.slice(-MAX_RECEIPTS).reverse();
+  top.forEach((e, i) => {
+    const failN = e.fail_count != null ? ` (${e.fail_count} failing)` : "";
+    L.push(`  ${i + 1}. your agent said:`);
+    L.push(`       "${clip(e.claim_text, 72)}"`);
+    L.push(`     but its own \`${clip(e.proof_command, 64)}\` had just FAILED${failN}:`);
+    if (e.evidence) L.push(`       ${clip(e.evidence, 72)}`);
+    // MEASURED time — shown ONLY when a real later same-proof PASS exists in the log. Never estimated.
+    if (e.fix_delta_ms != null) {
+      const dur = formatDuration(e.fix_delta_ms);
+      if (dur)
+        L.push(
+          `     ⏱  ${dur} later, that same proof was logged PASS (measured, real timestamps).`,
+        );
+    } else {
+      L.push("     ⏱  no later PASS logged for this proof yet — count only, no time estimated.");
+    }
+    L.push("");
+  });
+
+  if (falseCount > top.length)
+    L.push(`  …and ${falseCount - top.length} more FALSE in the ledger.`);
+  if (ledger.unverifiableCount > 0) {
+    L.push(
+      `  (${ledger.unverifiableCount} claim(s) logged but unverifiable — no re-runnable proof or harness noise; not counted as checked.)`,
+    );
+  }
+  L.push("  " + "─".repeat(74));
+  L.push(`  Append-only local history: ${logPath}`);
+  L.push("");
+  return L.join("\n");
+}
+
+// ---------- CLI ----------
+const isMain = (() => {
+  try {
+    return (
+      Boolean(process.argv[1]) &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  try {
+    // Optional override so the verifier can point the ledger at a crafted log (tests / self-check).
+    const logPath = process.env.SKALPEL_LEDGER_LOG || VERIFY_LOG_PATH;
+    const rows = readLedgerRows(logPath);
+    const ledger = rows == null ? null : buildLedger(rows);
+    process.stdout.write(renderLedger(ledger, { logPath }) + "\n");
+  } catch {
+    // READ-ONLY + fail-open: never throw at the user.
+    process.stdout.write(
+      "\n  🔬 skalpel — could not read your claim-verification ledger on this machine.\n\n",
+    );
+  }
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.31",
+  "version": "4.0.32",
   "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

@@ -63,6 +63,7 @@ const KNOWN_SUBS = new Set([
   "xray",
   "catches",
   "card",
+  "ledger",
   "__build",
   "__verify-report",
 ]);
@@ -79,6 +80,7 @@ usage:
   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 ledger                                your running tally: N "done"s checked, M verified FALSE
   skalpel uninstall [--purge]                   remove the hooks + local data from this machine
 
 options:
@@ -896,6 +898,14 @@ async function main() {
     spawnSync("node", [join(__dir, "card.mjs"), ...argv.slice(1)], { stdio: "inherit" });
     return;
   }
+  // `skalpel ledger` — the PERSONAL TRUTH LEDGER: a LOCAL, READ-ONLY view DERIVED from the append-only
+  // verify-shadow.log — your running tally of "done" claims checked and how many were verified FALSE,
+  // with the receipts and (only where a real red->green timestamp delta exists) the measured time.
+  // Never re-runs a proof, never touches the network, never estimates a number.
+  if (sub === "ledger") {
+    spawnSync("node", [join(__dir, "ledger.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).