sticky-note-cli 2.5.0 → 2.5.1

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/sticky-note"><img src="https://img.shields.io/npm/v/sticky-note.svg?style=flat-square&color=f59e0b" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/sticky-note-cli"><img src="https://img.shields.io/npm/v/sticky-note-cli.svg?style=flat-square&color=f59e0b" alt="npm version" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License" /></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg?style=flat-square" alt="Node.js >= 16" /></a>
   <a href="#supported-tools"><img src="https://img.shields.io/badge/works%20with-Claude%20%C2%B7%20Copilot%20%C2%B7%20Codex-8b5cf6?style=flat-square" alt="Works with Claude, Copilot, Codex" /></a>
@@ -30,24 +30,23 @@
 
 ## The Problem
 
-Every developer using AI coding assistants starts every session from zero.
-The handoff between teammates happens in Slack and stand-ups — everywhere
-except inside the AI tool where the work actually happened.
+I have seen many agent-to-agent to orchestration systems and frameworks, but I still like working with other people.
+Other people that ALSO use agents to develop. I couldn't get my agent to understand what my friends agents were doing.
+So we built Sticky Note.
 
 ## The Solution
 
 Sticky Note captures what happened in each AI session (files touched, status,
 narrative, failed approaches) and surfaces it to teammates automatically on
-their next session start — ranked by relevance. No dashboards. No extra tools.
-Just shared files in your repo.
+their next session by relevance.
 
 ---
 
 ## What's New in V2.5
 
 - **Smart injection (two-tier)**: Stuck threads injected eagerly at session start; all other threads injected lazily when you first touch a file they authored — via built-in git blame attribution
-- **Thread resume (local)**: `npx sticky-note resume-thread --query "auth fix" --user alice` — natural language thread discovery with text similarity + file attribution ranking
-- **Built-in attribution engine**: `npx sticky-note get-line-attribution --file src/auth.ts` — maps file lines to commit SHAs via git blame, resolves to threads with line ranges. No external dependencies.
+- **Thread resume (local)**: `npx sticky-note-cli resume-thread --query "auth fix" --user alice` — natural language thread discovery with text similarity + file attribution ranking
+- **Built-in attribution engine**: `npx sticky-note-cli get-line-attribution --file src/auth.ts` — maps file lines to commit SHAs via git blame, resolves to threads with line ranges. No external dependencies.
 - **Git Notes storage**: Session attribution stored in `refs/notes/sticky-note` — survives rebase/amend
 - **Three-tier SHA resolution**: Git Notes → Audit JSONL → File+date heuristic — attribution never breaks
 - **PreToolUse hook**: New hook fires before each tool call for lazy injection with line-range detail
@@ -59,7 +58,7 @@ Just shared files in your repo.
 - **Relevance scoring**: Context injected based on file overlap, branch match, and recency
 - **Richer threads**: Narrative summaries, failed approaches, work type, activities
 - **Tombstone expiry**: Old threads are automatically cleaned up via `gc`
-- **Presence tracking**: See who's currently active with `npx sticky-note who`
+- **Presence tracking**: See who's currently active with `npx sticky-note-cli who`
 - **Codex support**: Wrapper script for post-session capture
 - **Separate config**: Team settings in `sticky-note-config.json`
 
@@ -70,7 +69,7 @@ Just shared files in your repo.
 ### 1. Install
 
 ```bash
-npx sticky-note init
+npx sticky-note-cli init
 ```
 
 This runs an interactive setup that:
@@ -111,7 +110,7 @@ that's always available as a static file.
 
 ### 1. Static Instruction Files (always available)
 
-`npx sticky-note init` deploys AI instruction files that teach each tool
+`npx sticky-note-cli init` deploys AI instruction files that teach each tool
 how to interact with Sticky Note:
 
 | File | Consumed by | Installed to |
@@ -121,7 +120,7 @@ how to interact with Sticky Note:
 
 These files contain thread field references, status icons, resume
 instructions, display formats, and query examples. They're wrapped in
-`<!-- sticky-note:start/end -->` markers so `npx sticky-note update` can
+`<!-- sticky-note:start/end -->` markers so `npx sticky-note-cli update` can
 refresh them without overwriting your own content.
 
 ### 2. Session Start Hook (`session-start.js`)
@@ -169,13 +168,13 @@ Runs **before each tool call**. Lazy injection tier:
 
 No external dependencies — uses built-in git blame.
 
-### 4. Resume Flow (`npx sticky-note resume <id>`)
+### 4. Resume Flow (`npx sticky-note-cli resume <id>`)
 
 A manual trigger that enables **cross-tool handoff** (e.g., Claude Code →
 Copilot CLI):
 
 ```
-npx sticky-note resume <thread-id>
+npx sticky-note-cli resume <thread-id>
 ```
 
 1. Writes the thread UUID to a `.sticky-resume` signal file.
@@ -259,7 +258,7 @@ the thread's `handoff_summary` field.
 open → stale  (auto, after stale_days with no activity)
 open → closed (on session end)
 stuck → closed (on session end or manual)
-closed → open  (via `npx sticky-note resume <id>`)
+closed → open  (via `npx sticky-note-cli resume <id>`)
 closed → expired (auto, tombstoned by gc after stale_days)
 ```
 
@@ -311,34 +310,34 @@ CLAUDE.md                         # AI instructions for Claude Code
 ## CLI Commands
 
 ```bash
-npx sticky-note init           # Interactive setup
-npx sticky-note init --codex   # Setup with Codex wrapper
-npx sticky-note update         # Update hook scripts (preserves data)
-npx sticky-note status         # Diagnostic report (includes attribution health)
-npx sticky-note threads        # List threads with status icons
-npx sticky-note resume         # List resumable threads
-npx sticky-note resume <id>    # Resume a previous thread
-npx sticky-note resume --clear # Cancel active resume
-npx sticky-note resume-thread  # Smart resume: --query, --user, --file (V2.5)
-npx sticky-note audit          # Query merged audit trail (all users)
-npx sticky-note who            # Show active and recent team members
-npx sticky-note switch <branch> # Safe branch switch (auto-stashes data)
-npx sticky-note gc             # Tombstone expired threads
-npx sticky-note reset          # Wipe all threads (--force, --keep-audit)
-npx sticky-note get-line-attribution # File→thread attribution with line ranges (V2.5)
-npx sticky-note checkpoint         # Set work-topic checkpoint for attribution (V2.5)
-npx sticky-note --version      # Show version
-npx sticky-note --help         # Show help
+npx sticky-note-cli init           # Interactive setup
+npx sticky-note-cli init --codex   # Setup with Codex wrapper
+npx sticky-note-cli update         # Update hook scripts (preserves data)
+npx sticky-note-cli status         # Diagnostic report (includes attribution health)
+npx sticky-note-cli threads        # List threads with status icons
+npx sticky-note-cli resume         # List resumable threads
+npx sticky-note-cli resume <id>    # Resume a previous thread
+npx sticky-note-cli resume --clear # Cancel active resume
+npx sticky-note-cli resume-thread  # Smart resume: --query, --user, --file (V2.5)
+npx sticky-note-cli audit          # Query merged audit trail (all users)
+npx sticky-note-cli who            # Show active and recent team members
+npx sticky-note-cli switch <branch> # Safe branch switch (auto-stashes data)
+npx sticky-note-cli gc             # Tombstone expired threads
+npx sticky-note-cli reset          # Wipe all threads (--force, --keep-audit)
+npx sticky-note-cli get-line-attribution # File→thread attribution with line ranges (V2.5)
+npx sticky-note-cli checkpoint         # Set work-topic checkpoint for attribution (V2.5)
+npx sticky-note-cli --version      # Show version
+npx sticky-note-cli --help         # Show help
 ```
 
 ### Audit Filters
 
 ```bash
-npx sticky-note audit --user alice
-npx sticky-note audit --file src/auth.ts
-npx sticky-note audit --since 2025-01-01
-npx sticky-note audit --session abc-123
-npx sticky-note audit --limit 100
+npx sticky-note-cli audit --user alice
+npx sticky-note-cli audit --file src/auth.ts
+npx sticky-note-cli audit --since 2025-01-01
+npx sticky-note-cli audit --session abc-123
+npx sticky-note-cli audit --limit 100
 ```
 
 ---
@@ -388,7 +387,7 @@ All tools call the same JavaScript hooks and share the same data files.
 
 ## Concurrent Usage & Merge Strategy
 
-`npx sticky-note init` adds a `.gitattributes` rule:
+`npx sticky-note-cli init` adds a `.gitattributes` rule:
 
 ```
 .sticky-note/sticky-note.json merge=union
@@ -412,9 +411,9 @@ Use one of these approaches:
 
 ```bash
 # Recommended: sticky-note CLI wrapper
-npx sticky-note switch <branch>
+npx sticky-note-cli switch <branch>
 
-# Or: git alias (set up by npx sticky-note init)
+# Or: git alias (set up by npx sticky-note-cli init)
 git sw <branch>
 ```
 
@@ -434,13 +433,13 @@ A: `merge=union` in `.gitattributes` handles most cases automatically.
 
 **Q: Can I close a thread manually?**
 A: Edit `sticky-note.json` and change the thread's `status` to `"closed"`,
-or run `npx sticky-note gc` to tombstone expired threads.
+or run `npx sticky-note-cli gc` to tombstone expired threads.
 
 **Q: Does this work offline?**
 A: Yes. Everything is local until you `git push`.
 
 **Q: How do I set up Codex?**
-A: Run `npx sticky-note init --codex`, then alias the wrapper:
+A: Run `npx sticky-note-cli init --codex`, then alias the wrapper:
 `alias sticky-codex=".claude/hooks/sticky-codex.sh"`
 
 ---

package/bin/cli.js

@@ -537,21 +537,44 @@ async function cmdInit() {
 
   // Add .gitattributes merge strategy
   const gitattrsPath = path.join(process.cwd(), ".gitattributes");
-  const mergeRule = ".sticky-note/sticky-note.json merge=union";
+  const oldMergeRule = ".sticky-note/sticky-note.json merge=union";
+  const mergeRule = ".sticky-note/sticky-note.json merge=sticky-note";
   let gitattrsContent = "";
   if (fs.existsSync(gitattrsPath)) {
     gitattrsContent = fs.readFileSync(gitattrsPath, "utf-8");
   }
-  if (!gitattrsContent.includes(mergeRule)) {
+  // Upgrade from merge=union to custom merge driver
+  if (gitattrsContent.includes(oldMergeRule)) {
+    gitattrsContent = gitattrsContent.replace(oldMergeRule, mergeRule);
+    fs.writeFileSync(gitattrsPath, gitattrsContent, "utf-8");
+    print("  [OK] .gitattributes upgraded (merge=union -> merge=sticky-note)");
+  } else if (!gitattrsContent.includes(mergeRule)) {
     const addition = gitattrsContent.endsWith("\n") || gitattrsContent === ""
-      ? `\n# Sticky Note - auto-merge threads from both sides\n${mergeRule}\n`
-      : `\n\n# Sticky Note - auto-merge threads from both sides\n${mergeRule}\n`;
+      ? `\n# Sticky Note - JSON-aware thread merge\n${mergeRule}\n`
+      : `\n\n# Sticky Note - JSON-aware thread merge\n${mergeRule}\n`;
     fs.appendFileSync(gitattrsPath, addition);
-    print("  [OK] .gitattributes updated (merge=union)");
+    print("  [OK] .gitattributes updated (merge=sticky-note)");
   } else {
     print("  ⏭️  .gitattributes already configured");
   }
 
+  // Install merge driver script and git config
+  const mergeDriverSrc = path.join(TEMPLATES_DIR, "merge-driver.js");
+  const mergeDriverDest = path.join(stickyDir, "merge-driver.js");
+  copyFile(mergeDriverSrc, mergeDriverDest);
+  print("  [OK] .sticky-note/merge-driver.js installed");
+  try {
+    execFileSync("git", ["config", "merge.sticky-note.name", "Sticky Note thread merge"], {
+      cwd: process.cwd(), stdio: ["pipe", "pipe", "pipe"],
+    });
+    execFileSync("git", ["config", "merge.sticky-note.driver", "node .sticky-note/merge-driver.js %O %A %B"], {
+      cwd: process.cwd(), stdio: ["pipe", "pipe", "pipe"],
+    });
+    print("  [OK] git merge driver configured (merge.sticky-note)");
+  } catch (_) {
+    print("  ⏭️  Could not configure git merge driver (non-fatal)");
+  }
+
   // Add git aliases for safe branch switching
   try {
     const swAlias = '!f() { npx sticky-note switch "$@"; }; f';
@@ -668,6 +691,38 @@ function cmdUpdate() {
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
   }
 
+  // Update merge driver
+  const mergeDriverSrc = path.join(TEMPLATES_DIR, "merge-driver.js");
+  const mergeDriverDest = path.join(stickyDir, "merge-driver.js");
+  copyFile(mergeDriverSrc, mergeDriverDest);
+  print("  [OK] .sticky-note/merge-driver.js updated");
+
+  // Upgrade .gitattributes from merge=union to custom driver
+  const gitattrsPath = path.join(process.cwd(), ".gitattributes");
+  if (fs.existsSync(gitattrsPath)) {
+    let gitattrsContent = fs.readFileSync(gitattrsPath, "utf-8");
+    const oldRule = ".sticky-note/sticky-note.json merge=union";
+    const newRule = ".sticky-note/sticky-note.json merge=sticky-note";
+    if (gitattrsContent.includes(oldRule)) {
+      gitattrsContent = gitattrsContent.replace(oldRule, newRule);
+      fs.writeFileSync(gitattrsPath, gitattrsContent, "utf-8");
+      print("  [OK] .gitattributes upgraded (merge=union -> merge=sticky-note)");
+    }
+  }
+
+  // Ensure git merge driver config is set
+  try {
+    execFileSync("git", ["config", "merge.sticky-note.name", "Sticky Note thread merge"], {
+      cwd: process.cwd(), stdio: ["pipe", "pipe", "pipe"],
+    });
+    execFileSync("git", ["config", "merge.sticky-note.driver", "node .sticky-note/merge-driver.js %O %A %B"], {
+      cwd: process.cwd(), stdio: ["pipe", "pipe", "pipe"],
+    });
+    print("  [OK] git merge driver configured (merge.sticky-note)");
+  } catch (_) {
+    // non-fatal
+  }
+
   print(`\n  ✨ Scripts updated to v${VERSION}`);
 
   // Update instruction files (section-based: only replaces between markers)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sticky-note-cli",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Human-to-human handoff for AI coding assistants. Git-backed shared memory for Claude Code and Copilot CLI.",
   "license": "MIT",
   "bin": {

package/templates/hooks/inject-context.js

@@ -50,7 +50,7 @@ try {
   gitNotes = null;
 }
 const {
-  getMemoryPath, loadJson, saveJson, getUser, getBranch,
+  getMemoryPath, loadJson, saveJson, saveMemoryMerged, getUser, getBranch,
   getResumeThreadId, findThreadById, getSessionId,
   appendAuditLine, detectTool, getConfigPath,
   isThreadInjected, markThreadInjected, normalizeSep,
@@ -391,7 +391,7 @@ function main() {
 
   if (memoryDirty) {
     try {
-      saveJson(getMemoryPath(), memory);
+      saveMemoryMerged(getMemoryPath(), memory);
     } catch (_) {
       // ignore
     }

package/templates/hooks/on-error.js

@@ -19,12 +19,13 @@ function _safeExit() {
   process.exit(0);
 }
 
-let getMemoryPath, loadJson, saveJson, appendAuditLine, getUser, detectTool, getSessionId;
+let getMemoryPath, loadJson, saveJson, saveMemoryMerged, appendAuditLine, getUser, detectTool, getSessionId;
 try {
   ({
     getMemoryPath,
     loadJson,
     saveJson,
+    saveMemoryMerged,
     appendAuditLine,
     getUser,
     detectTool,
@@ -118,7 +119,7 @@ function main() {
     tool: toolName,
   });
 
-  saveJson(memoryPath, memory);
+  saveMemoryMerged(memoryPath, memory);
   const statusMsg = `[STICKY-NOTE] Marked thread as STUCK - ${errorMsg.substring(0, 80)}`;
   try {
     process.stdout.write(JSON.stringify({ output: statusMsg }) + "\n");

package/templates/hooks/on-stop.js

@@ -29,6 +29,7 @@ const {
   getMemoryPath,
   loadJson,
   saveJson,
+  saveMemoryMerged,
   appendAuditLine,
   getUser,
   getBranch,
@@ -132,7 +133,7 @@ function main() {
     reason: reason ? reason.substring(0, 200) : "stop_checkpoint",
   });
 
-  saveJson(memoryPath, memory);
+  saveMemoryMerged(memoryPath, memory);
   const reasonStr = reason ? reason.substring(0, 60) : "checkpoint";
   const statusMsg = `[STICKY-NOTE] Session stopped - handoff saved (${reasonStr})`;
   try {

package/templates/hooks/session-end.js

@@ -36,6 +36,7 @@ const {
   getAllAuditPaths,
   loadJson,
   saveJson,
+  saveMemoryMerged,
   appendAuditLine,
   getUser,
   getBranch,
@@ -932,7 +933,7 @@ function main() {
     clearHeadFile();
     clearInjectedSet();
   }
-  saveJson(memoryPath, memory);
+  saveMemoryMerged(memoryPath, memory);
 
   const fileCount = filesTouched.length;
   const commitCount = commitShas.length;

package/templates/hooks/session-start.js

@@ -34,6 +34,7 @@ const {
   migrateAuditAndPresence,
   loadJson,
   saveJson,
+  saveMemoryMerged,
   appendAuditLine,
   getUser,
   getSessionId,
@@ -270,7 +271,7 @@ function main() {
         resumed_from: prevSession,
       });
       resumedThread.resume_chain = chain;
-      saveJson(memoryPath, memory);
+      saveMemoryMerged(memoryPath, memory);
     }
   }
 
@@ -293,7 +294,7 @@ function main() {
     session_id: sessionId,
   });
 
-  saveJson(memoryPath, memory);
+  saveMemoryMerged(memoryPath, memory);
 
   // ── Assemble output ───────────────────────────────────
   const parts = [];

package/templates/hooks/sticky-utils.js

@@ -205,6 +205,31 @@ function saveJson(filePath, data) {
   fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
 }
 
+/**
+ * Merge-on-write for the memory file. Re-reads the file from disk before
+ * writing and preserves any threads (by ID) that exist on disk but not in
+ * the in-memory copy. This prevents concurrent sessions or un-pulled commits
+ * from silently dropping other users' threads.
+ */
+function saveMemoryMerged(memoryPath, memory) {
+  try {
+    const onDisk = loadJson(memoryPath, { threads: [] });
+    const onDiskThreads = Array.isArray(onDisk.threads) ? onDisk.threads : [];
+    const inMemoryThreads = Array.isArray(memory.threads) ? memory.threads : [];
+    const inMemoryIds = new Set(inMemoryThreads.map((t) => t.id));
+
+    for (const diskThread of onDiskThreads) {
+      if (diskThread.id && !inMemoryIds.has(diskThread.id)) {
+        memory.threads.push(diskThread);
+      }
+    }
+  } catch (_) {
+    // If re-read fails, proceed with what we have
+  }
+
+  saveJson(memoryPath, memory);
+}
+
 function appendAuditLine(entry) {
   const filePath = getUserAuditPath();
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -618,6 +643,7 @@ module.exports = {
   clearResumeSignal,
   loadJson,
   saveJson,
+  saveMemoryMerged,
   appendAuditLine,
   getUser,
   detectTool,

package/templates/merge-driver.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Git custom merge driver for sticky-note.json
+ *
+ * Merges threads by ID instead of line-based union merge.
+ * For threads present in both sides, the version with the latest
+ * last_activity_at wins. Threads unique to either side are preserved.
+ *
+ * Usage (called by git automatically):
+ *   node .sticky-note/merge-driver.js %O %A %B
+ *
+ * %O = ancestor, %A = ours (result written here), %B = theirs
+ */
+
+const fs = require("fs");
+
+function loadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (_) {
+    return { version: "2", project: "", threads: [] };
+  }
+}
+
+function getTimestamp(thread) {
+  const ts = thread.last_activity_at || thread.closed_at || thread.created_at || "";
+  if (!ts) return 0;
+  const t = new Date(ts).getTime();
+  return isNaN(t) ? 0 : t;
+}
+
+function mergeThreads(ancestor, ours, theirs) {
+  const ancestorMap = new Map((ancestor.threads || []).map((t) => [t.id, t]));
+  const oursMap = new Map((ours.threads || []).map((t) => [t.id, t]));
+  const theirsMap = new Map((theirs.threads || []).map((t) => [t.id, t]));
+
+  const allIds = new Set([...oursMap.keys(), ...theirsMap.keys()]);
+  const merged = [];
+
+  for (const id of allIds) {
+    const inOurs = oursMap.has(id);
+    const inTheirs = theirsMap.has(id);
+    const inAncestor = ancestorMap.has(id);
+
+    if (inOurs && inTheirs) {
+      // Both sides have it — pick the most recently active version
+      const o = oursMap.get(id);
+      const t = theirsMap.get(id);
+      merged.push(getTimestamp(o) >= getTimestamp(t) ? o : t);
+    } else if (inOurs && !inTheirs) {
+      // Only in ours — keep unless theirs deliberately removed it
+      if (inAncestor) {
+        // Was in ancestor, theirs removed it — respect the deletion
+      } else {
+        merged.push(oursMap.get(id));
+      }
+    } else if (!inOurs && inTheirs) {
+      // Only in theirs — keep unless ours deliberately removed it
+      if (inAncestor) {
+        // Was in ancestor, ours removed it — respect the deletion
+      } else {
+        merged.push(theirsMap.get(id));
+      }
+    }
+  }
+
+  return merged;
+}
+
+// ── Main ──────────────────────────────────────────────────
+
+const [ancestorPath, oursPath, theirsPath] = process.argv.slice(2);
+
+if (!ancestorPath || !oursPath || !theirsPath) {
+  process.stderr.write("Usage: merge-driver.js <ancestor> <ours> <theirs>\n");
+  process.exit(1);
+}
+
+const ancestor = loadJson(ancestorPath);
+const ours = loadJson(oursPath);
+const theirs = loadJson(theirsPath);
+
+const mergedThreads = mergeThreads(ancestor, ours, theirs);
+
+// Use ours as the base for non-thread fields (version, project, etc.)
+const result = { ...ours, threads: mergedThreads };
+
+fs.writeFileSync(oursPath, JSON.stringify(result, null, 2) + "\n", "utf-8");
+process.exit(0);