skalpel 4.0.2 → 4.0.4

package/install.mjs

@@ -40,6 +40,7 @@ function stageHookRuntime() {
   // this rule and is guarded by the all-or-nothing check below instead).
   // a hook entrypoint staged without a module it imports — the exact 0.3.12–0.3.16 bug shape.
   copyFileSync(join(PKG_DIR, "insights.mjs"), join(HOOKS_DIR, "insights.mjs")); // hooks import ./insights.mjs
+  copyFileSync(join(PKG_DIR, "reveal.mjs"), join(HOOKS_DIR, "reveal.mjs")); // both hooks import ./reveal.mjs
   copyFileSync(join(PKG_DIR, "skalpel-hook.mjs"), HOOK_FILE);
   copyFileSync(join(PKG_DIR, "skalpel-hook-session.mjs"), SESSION_FILE);
   copyFileSync(join(PKG_DIR, "incremental-ingest.mjs"), join(HOOKS_DIR, "incremental-ingest.mjs"));

package/package.json

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

package/reveal.mjs

@@ -0,0 +1,61 @@
+// reveal.mjs — the one-shot "your graph is ready" reveal, shared by both hooks.
+//
+// The detached background build (skalpel-setup __build) drops ~/.skalpel/insights-ready.json when it
+// finishes. The FIRST hook to fire after that (the next per-turn prompt OR the next session start)
+// surfaces this reveal IN the Claude Code conversation — the native surface, no OS pop-up — then clears
+// the marker so it shows exactly once.
+//
+// Tone: this is the first time the user is seeing what skalpel learned about them, so the note directs
+// the model to TEACH them their own pattern in plain, warm English — never the internal notation, never
+// a stats dump.
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function graphReadyNote() {
+  const p = join(homedir(), ".skalpel", "insights-ready.json");
+  let m;
+  try {
+    m = JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null; // nothing pending
+  }
+  if (!m || !m.ready) return null;
+  try {
+    writeFileSync(p, JSON.stringify({ ready: false })); // one-shot — clear so it never repeats
+  } catch {
+    /* if we can't clear it, better to drop the reveal than repeat it — but proceed once */
+  }
+
+  const h = (m.report && m.report.headline) || {};
+  const trap = m.report && (m.report.discriminative || [])[0] && m.report.discriminative[0].seq;
+  const n = m.n_sessions || h.sessions || 0;
+
+  const facts = [];
+  if (h.hours)
+    facts.push(`they've spent about ${h.hours} hours working with AI across these sessions`);
+  if (h.rework_pct)
+    facts.push(
+      `roughly ${h.rework_pct}% of that time went into REWORK — going back to redo, re-explain, or ` +
+        `re-fix things they'd already worked on (that's the time skalpel is built to give back)`,
+    );
+  if (trap)
+    facts.push(
+      `the habit that most often kicks off that loop, in their own history, is the sequence "${trap}" ` +
+        `— TRANSLATE this into plain human language (e.g. "you ask me to explain something, then keep ` +
+        `refining the same thing in circles") and NEVER show the raw sequence or any arrow notation`,
+    );
+
+  return (
+    `[skalpel — the user's behavioral graph just finished building in the background, from ${n} of ` +
+    `their recent coding sessions. This is the FIRST time they're seeing what it learned about them, so ` +
+    `explain it like they've never seen their own patterns before: warm, plain, concrete — NO jargon, ` +
+    `NO internal notation, NO stats dump. Open your reply with ONE short line — ` +
+    `"🔬 skalpel · your graph's ready — here's what I noticed about how you work:" — then, in 2-3 ` +
+    `friendly plain-English sentences, tell them what it found` +
+    (facts.length ? `: ${facts.join("; ")}` : "") +
+    `. Close by reassuring them this is exactly the loop skalpel now quietly watches for and steers them ` +
+    `out of, live, while they code — they don't have to track it themselves. Then continue with whatever ` +
+    `they actually asked. Keep the whole thing short and human.]`
+  );
+}

package/skalpel-hook-session.mjs

@@ -12,6 +12,7 @@ import { join } from "node:path";
 import { identity } from "./auth.mjs";
 import { record } from "./metrics.mjs";
 import { recordInsight } from "./insights.mjs";
+import { graphReadyNote } from "./reveal.mjs";
 
 // The statusline counter is PER-SESSION: it shows the estimated rework skalpel flagged during THIS
 // session, not a forever-accumulating lifetime total (which reads as a bragging trophy and is
@@ -121,38 +122,6 @@ const API = process.env.SKALPEL_API || CFG.api || "https://graph.skalpel.ai";
 // load with ~1s margin under the 8s backstop; warm it still returns in ~300ms, so no cost when hot.
 const DEADLINE_MS = 7000;
 
-// One-shot reveal: the detached background build drops ~/.skalpel/insights-ready.json when it
-// finishes. Surface it ONCE at the next session start, then clear it — so the user sees "your graph is
-// ready + here's what I learned" the moment it lands. This is the payoff of the async build.
-function graphReadyNote() {
-  const p = join(homedir(), ".skalpel", "insights-ready.json");
-  let m;
-  try {
-    m = JSON.parse(readFileSync(p, "utf8"));
-  } catch {
-    return null; // nothing pending
-  }
-  if (!m || !m.ready) return null;
-  try {
-    writeFileSync(p, JSON.stringify({ ready: false })); // one-shot — clear so it never repeats
-  } catch {
-    /* if we can't clear it we'd rather drop the reveal than repeat it, but proceed */
-  }
-  const h = (m.report && m.report.headline) || {};
-  const trap = m.report && (m.report.discriminative || [])[0] && m.report.discriminative[0].seq;
-  const n = m.n_sessions || h.sessions || 0;
-  const bits = [];
-  if (h.hours) bits.push(`~${h.hours}h with AI`);
-  if (h.rework_pct) bits.push(`~${h.rework_pct}% of it went to rework`);
-  if (trap) bits.push(`your signature trap is ${trap}`);
-  const learned = bits.length ? ` I learned: ${bits.join(", ")}.` : "";
-  return (
-    `[skalpel — the user's behavioral graph just FINISHED building in the background ` +
-    `(${n} session${n === 1 ? "" : "s"}). Open THIS reply with ONE natural line so they see it landed, ` +
-    `in skalpel's voice: "🔬 skalpel · your graph is ready —${learned}" Then continue normally.]`
-  );
-}
-
 async function main() {
   let payload = {};
   try {

package/skalpel-hook.mjs

@@ -14,6 +14,7 @@ import { join } from "node:path";
 import { identity } from "./auth.mjs";
 import { record } from "./metrics.mjs";
 import { recordInsight } from "./insights.mjs";
+import { graphReadyNote } from "./reveal.mjs";
 
 // Config precedence: env > ~/.skalpel/client.json (written by `skalpel-prosumer setup`) > default.
 function fileCfg() {
@@ -682,9 +683,13 @@ async function main() {
       session_id: sessionId,
     });
 
-  // ackNote (feedback confirmation) leads, then the reset interrupt (most acute), the server steer,
-  // and the win note. Any can fire alone.
-  const additionalContext = [ackNote, resetNote, winNote, injection].filter(Boolean).join("\n\n");
+  // A just-finished background build leads (one-shot: surface "your graph's ready" the instant the next
+  // prompt fires, so the user doesn't have to restart a session to see it), then ackNote (feedback
+  // confirmation), the reset interrupt (most acute), the server steer, and the win note. Any can fire alone.
+  const readyNote = graphReadyNote();
+  const additionalContext = [readyNote, ackNote, resetNote, winNote, injection]
+    .filter(Boolean)
+    .join("\n\n");
   if (additionalContext) {
     process.stdout.write(
       JSON.stringify({

package/skalpel-setup.mjs

@@ -902,6 +902,9 @@ async function backgroundBuild() {
     } catch {
       /* profile fetch is best-effort — the graph is still built */
     }
+    // The reveal surfaces NATIVELY inside Claude Code — the next prompt's hook (or the next session)
+    // opens with "🔬 your graph's ready — here's what I noticed about how you work" from this marker.
+    // No OS pop-up: skalpel's whole surface is the conversation + the status line.
     try {
       mkdirSync(join(homedir(), ".skalpel"), { recursive: true });
       writeFileSync(
@@ -909,39 +912,13 @@ async function backgroundBuild() {
         JSON.stringify({ ready: true, ts: Date.now(), n_sessions: built, report }),
       );
     } catch {
-      /* the SessionStart reveal is a bonus; never block the build on it */
+      /* the reveal is a bonus; never block the build on it */
     }
-    notifyDone(built);
   } catch {
     /* fail-open: a failed background build never surfaces; hooks fail open until it succeeds */
   }
 }
 
-// Desktop notification when the background build finishes — cross-platform, best-effort, never throws.
-function notifyDone(n) {
-  const title = "skalpel";
-  const msg = `Your graph is ready — learned from ${n} session${n === 1 ? "" : "s"}. Open Claude Code to see your insights.`;
-  try {
-    if (process.platform === "darwin") {
-      spawnSync(
-        "osascript",
-        ["-e", `display notification ${JSON.stringify(msg)} with title ${JSON.stringify(title)}`],
-        { stdio: "ignore" },
-      );
-    } else if (process.platform === "linux") {
-      spawnSync("notify-send", [title, msg], { stdio: "ignore" });
-    } else if (process.platform === "win32") {
-      spawnSync(
-        "powershell",
-        ["-NoProfile", "-Command", `New-BurntToastNotification -Text '${title}','${msg}'`],
-        { stdio: "ignore" },
-      );
-    }
-  } catch {
-    /* notifications are best-effort */
-  }
-}
-
 // `__build` = the detached background graph build spawned by setup; skips the banner/hooks entirely.
 if (isMain && sub === "__build") {
   backgroundBuild()