get-claudia 1.55.21 → 1.56.1

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to Claudia will be documented in this file.
 
+## 1.56.1 (2026-04-11)
+
+### Preserve User-Modified Skills on Upgrade
+
+Re-running the installer in an existing project no longer silently overwrites skills, rules, or `CLAUDE.md` that the user has customized. Three-way merge via a shipped manifest detects which tracked files the user has edited and prompts before touching them.
+
+#### Added
+- **`template-v2/.claude/manifest.json`** -- SHA-256 hashes of every shipped file under `.claude/skills/`, `.claude/rules/`, and `CLAUDE.md`. Regenerated on `npm publish` via `prepublishOnly`. Users get the new manifest automatically on every upgrade so the next upgrade has a clean comparison baseline.
+- **`bin/manifest-lib.js`** -- Pure-function library: `hashFile`, `generateManifest`, `detectConflicts`, `resolveBakPath`, `applyResolution`, `loadManifest`. No runtime dependencies.
+- **`scripts/generate-manifest.js`** -- Standalone CLI wrapper: `npm run generate-manifest` rebuilds the shipped manifest from the current `template-v2/` tree.
+- **Batch conflict prompt** -- When an upgrade would overwrite locally-modified files, the installer prints a summary and offers `[k]eep all`, `[o]verwrite all`, `[r]eview each`, or `[c]ancel`. Review-each supports `[d]iff` (uses `git diff --no-index` when available), and `[s]kip rest`.
+- **Automatic `.bak` backups** -- Any file the user chooses to overwrite is first copied to `<file>.bak` (with numeric suffix on collision: `.bak.1`, `.bak.2`, ...). No existing `.bak` file is ever overwritten.
+- **25 tests** -- 22 unit tests in `test/manifest.test.js` plus 3 integration tests in `test/integration.test.js`. Run with `npm test`. Uses Node's built-in `node:test`; zero new dependencies.
+
+#### Changed
+- **Upgrade copy path** in `bin/index.js` now runs conflict detection before `cpSync` and passes a filter callback that skips any file the user chose to keep. The fresh-install path is unchanged.
+- **Non-TTY and `--yes` mode** defaults to keep-all for conflicts, printing what was preserved. Safe for CI.
+
+#### Notes
+- Manifest scope is deliberately narrow: `.claude/skills/**`, `.claude/rules/**`, and `CLAUDE.md`. Files under `hooks/`, `agents/`, `commands/`, `workspaces/`, and `settings.local.json` are excluded.
+- Missing or corrupt user manifest falls back to direct hash comparison against the new template -- the upgrade does not crash.
+- On the first upgrade after this feature ships, users will see a slightly noisier prompt because there's no prior manifest to diff against. Every subsequent upgrade is clean.
+
+#### Rollback
+Single atomic commit. `git revert <sha>` undoes everything. Pre-push `origin/main` was `2d65baa`.
+
+---
+
+## 1.56.0 (2026-04-01)
+
+### Claude Desktop Compatibility
+
+MCP tool names migrated from dot notation (`memory.recall`) to underscore notation (`memory_recall`) to comply with the MCP spec's `^[a-zA-Z0-9_-]{1,64}$` requirement. Claude Code tolerated dots; Claude Desktop rejected them at registration, blocking Desktop users entirely.
+
+#### Fixed
+- **Tool names comply with MCP spec** -- All 33 memory tools renamed from `memory.xxx` to `memory_xxx` in the daemon server, scheduler, and test assertions (PR #32)
+- **Instructional references updated** -- ~200 tool name references renamed across CLAUDE.md, skills (memory-manager, morning-brief, deep-context, meditate, capture-meeting, meeting-prep, research), hooks (pre-compact, hooks.json, post-tool-capture), rules (memory-availability, claudia-principles), README, bin/index.js, and internal error messages
+- **template-v2/ mirrors synced** -- New installations get underscore names from day one
+
+#### Added
+- **Backward-compatible alias layer** -- The daemon registers dot-notation aliases (`memory.recall` resolves to the same handler as `memory_recall`) so users who haven't restarted their session or updated their skills keep working during the transition
+- **test_tool_name_compat.py** -- 6 new tests proving aliases are registered, `list_tools()` only advertises underscore names, and `cognitive.ingest` is unaffected
+
+#### Stats
+- 762 tests pass, 0 regressions (+6 new tests)
+- 30 files changed across 3 directory trees (root, claudia/, template-v2/)
+
+---
+
 ## 1.55.21 (2026-03-19)
 
 ### The Community Release

package/bin/index.js

@@ -1,12 +1,19 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, cpSync, readdirSync, readFileSync, writeFileSync, statSync, renameSync, unlinkSync } from 'fs';
+import { existsSync, mkdirSync, cpSync, readdirSync, readFileSync, writeFileSync, statSync, renameSync, unlinkSync, copyFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { spawn, execFileSync } from 'child_process';
 import { homedir } from 'os';
 import { createInterface } from 'readline';
 import { setupGoogleWorkspace, detectOldGoogleMcp, extractProjectNumber, buildApiEnableUrl, TIER_APIS } from './google-setup.js';
+import {
+  loadManifest,
+  generateManifest,
+  detectConflicts,
+  resolveBakPath,
+  applyResolution,
+} from './manifest-lib.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -70,6 +77,181 @@ function confirm(question) {
   });
 }
 
+// Single-keystroke prompt. Returns the lowercased first character of the
+// user's answer, or `defaultKey` when non-TTY / --yes.
+function promptKey(question, validKeys, defaultKey) {
+  if (!isTTY || process.argv.includes('--yes') || process.argv.includes('-y')) {
+    return Promise.resolve(defaultKey);
+  }
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      const c = (answer || '').trim().toLowerCase().charAt(0);
+      if (validKeys.includes(c)) resolve(c);
+      else resolve(defaultKey);
+    });
+  });
+}
+
+// Detect + resolve conflicts between shipped framework files and the user's
+// locally modified versions. Returns the set of relative paths the caller
+// must skip during cpSync. Saves .bak siblings for any file the user chose
+// to overwrite. May exit(0) if the user cancels.
+async function handleSkillConflicts(targetPath, templatePath) {
+  const userManifestPath = join(targetPath, '.claude', 'manifest.json');
+  const newManifestPath = join(templatePath, '.claude', 'manifest.json');
+
+  const oldManifest = loadManifest(userManifestPath);
+  let newManifest = loadManifest(newManifestPath);
+
+  // If the shipped manifest is missing (older package or dev build), fall
+  // back to generating one on the fly from the template tree. This keeps
+  // the feature working even when scripts/generate-manifest.js wasn't run.
+  if (!newManifest) {
+    try {
+      newManifest = generateManifest(templatePath, { version: getVersion() });
+    } catch {
+      return new Set(); // can't detect conflicts; preserve old behavior
+    }
+  }
+
+  const result = detectConflicts({
+    userDir: targetPath,
+    templateDir: templatePath,
+    oldManifest,
+    newManifest,
+  });
+
+  if (result.conflicts.length === 0) {
+    return new Set(); // nothing to prompt about
+  }
+
+  // Non-TTY or --yes → default to keeping user versions (safe in CI).
+  const isNonInteractive = !isTTY || process.argv.includes('--yes') || process.argv.includes('-y');
+
+  console.log('');
+  console.log(` ${colors.yellow}⚠${colors.reset}  ${result.conflicts.length} file(s) have local modifications that would be overwritten:`);
+  console.log('');
+  for (const f of result.conflicts) {
+    console.log(`    ${colors.dim}${f}${colors.reset}`);
+  }
+  console.log('');
+
+  if (isNonInteractive) {
+    console.log(` ${colors.cyan}i${colors.reset}  Non-interactive mode — keeping your versions. Updates for these files skipped.`);
+    console.log('');
+    return new Set(result.conflicts);
+  }
+
+  console.log(' How do you want to handle these?');
+  console.log(`   ${colors.bold}[k]${colors.reset} Keep all my versions (skip updates for these files)`);
+  console.log(`   ${colors.bold}[o]${colors.reset} Overwrite all ${colors.dim}(saves your versions as .bak)${colors.reset}`);
+  console.log(`   ${colors.bold}[r]${colors.reset} Review each one`);
+  console.log(`   ${colors.bold}[c]${colors.reset} Cancel upgrade`);
+  console.log('');
+
+  const topChoice = await promptKey(' Choice: ', ['k', 'o', 'r', 'c'], 'k');
+
+  let resolution;
+  if (topChoice === 'k') {
+    resolution = applyResolution(result.conflicts, { choice: 'keep-all' });
+  } else if (topChoice === 'o') {
+    resolution = applyResolution(result.conflicts, { choice: 'overwrite-all' });
+  } else if (topChoice === 'c') {
+    resolution = applyResolution(result.conflicts, { choice: 'cancel' });
+  } else {
+    // review each
+    const perFile = {};
+    let skipRest = false;
+    for (const f of result.conflicts) {
+      if (skipRest) {
+        perFile[f] = 'keep';
+        continue;
+      }
+      console.log('');
+      console.log(`   ${colors.cyan}•${colors.reset} ${f}`);
+      const k = await promptKey(
+        `     ${colors.bold}[k]${colors.reset}eep / ${colors.bold}[o]${colors.reset}verwrite / ${colors.bold}[d]${colors.reset}iff / ${colors.bold}[s]${colors.reset}kip rest: `,
+        ['k', 'o', 'd', 's'],
+        'k',
+      );
+      if (k === 'd') {
+        showDiff(join(targetPath, f), join(templatePath, f));
+        // Re-prompt after showing the diff
+        const k2 = await promptKey(
+          `     ${colors.bold}[k]${colors.reset}eep / ${colors.bold}[o]${colors.reset}verwrite: `,
+          ['k', 'o'],
+          'k',
+        );
+        perFile[f] = k2 === 'o' ? 'overwrite' : 'keep';
+      } else if (k === 's') {
+        perFile[f] = 'keep';
+        skipRest = true;
+      } else {
+        perFile[f] = k === 'o' ? 'overwrite' : 'keep';
+      }
+    }
+    resolution = applyResolution(result.conflicts, { choice: 'per-file', perFile });
+  }
+
+  if (resolution.cancelled) {
+    console.log('');
+    console.log(` ${colors.dim}Upgrade cancelled. No files changed.${colors.reset}`);
+    process.exit(0);
+  }
+
+  // Back up user versions for any file they chose to overwrite
+  for (const relPath of resolution.overwrite) {
+    const userAbs = join(targetPath, relPath);
+    if (existsSync(userAbs)) {
+      try {
+        const bakAbs = resolveBakPath(userAbs);
+        copyFileSync(userAbs, bakAbs);
+        console.log(` ${colors.cyan}↺${colors.reset}  Backed up ${colors.dim}${relPath}${colors.reset} → ${colors.dim}${bakAbs.replace(targetPath + '/', '')}${colors.reset}`);
+      } catch (err) {
+        console.log(` ${colors.red}!${colors.reset}  Failed to back up ${relPath}: ${err.message}`);
+      }
+    }
+  }
+
+  if (resolution.skip.length > 0) {
+    console.log('');
+    console.log(` ${colors.green}✓${colors.reset} Kept your versions of ${resolution.skip.length} file(s).`);
+  }
+
+  return new Set(resolution.skip);
+}
+
+// Best-effort diff display. Uses `git diff --no-index` if git is on PATH;
+// otherwise prints a plain head-of-each-file comparison.
+function showDiff(userAbs, templateAbs) {
+  try {
+    const out = execFileSync('git', ['diff', '--no-index', '--no-color', userAbs, templateAbs], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+    console.log(out);
+  } catch (err) {
+    // git diff --no-index returns exit 1 when files differ — that's normal
+    if (err.stdout) {
+      console.log(err.stdout);
+      return;
+    }
+    // No git available — fall back to naive display
+    try {
+      const userLines = readFileSync(userAbs, 'utf8').split('\n').slice(0, 40);
+      const tmplLines = readFileSync(templateAbs, 'utf8').split('\n').slice(0, 40);
+      console.log(`     ${colors.dim}--- your version (first 40 lines) ---${colors.reset}`);
+      userLines.forEach((l) => console.log(`     ${l}`));
+      console.log(`     ${colors.dim}--- shipped version (first 40 lines) ---${colors.reset}`);
+      tmplLines.forEach((l) => console.log(`     ${l}`));
+    } catch {
+      console.log(`     ${colors.dim}(diff unavailable)${colors.reset}`);
+    }
+  }
+}
+
 // Compact portrait-only banner
 function getBanner(version) {
   if (!isTTY) {
@@ -646,6 +828,26 @@ async function main() {
     // Upgrade: copy framework files, preserve user data
     const frameworkPaths = ['.claude', 'CLAUDE.md', '.mcp.json.example', 'LICENSE', 'NOTICE', 'workspaces'];
 
+    // Detect user-modified shipped files and let the user decide what to
+    // do before we touch anything. Returns a Set of POSIX-relative paths
+    // to exclude from the copy; may exit(0) if the user cancels.
+    let skipPaths;
+    try {
+      skipPaths = await handleSkillConflicts(targetPath, templatePath);
+    } catch (err) {
+      // Conflict detection must never break the upgrade. Fall back to the
+      // original copy-over-top behavior with a warning.
+      console.log(` ${colors.yellow}!${colors.reset}  Conflict detection failed (${err.message}); falling back to overwrite.`);
+      skipPaths = new Set();
+    }
+
+    // Build an absolute-path skip set for the cpSync filter callback.
+    const skipAbs = new Set();
+    for (const rel of skipPaths) {
+      skipAbs.add(join(targetPath, rel));
+    }
+    const copyFilter = (_src, dest) => !skipAbs.has(dest);
+
     try {
       for (const item of frameworkPaths) {
         const src = join(templatePath, item);
@@ -654,9 +856,12 @@ async function main() {
 
         const srcStat = statSync(src);
         if (srcStat.isDirectory()) {
-          cpSync(src, dest, { recursive: true, force: true });
+          cpSync(src, dest, { recursive: true, force: true, filter: copyFilter });
         } else {
-          cpSync(src, dest, { force: true });
+          // For top-level files (CLAUDE.md, LICENSE, etc.), check skip manually
+          if (!skipAbs.has(dest)) {
+            cpSync(src, dest, { force: true });
+          }
         }
       }
 
@@ -1932,7 +2137,7 @@ ${contextual.map(s => `- **/${s.name}** - ${s.description}`).join('\n')}
 ${explicit.map(s => `- **/${s.name}** - ${s.description}`).join('\n')}
 
 ## Memory System
-Memory operations use MCP tools from the claudia-memory daemon (memory.recall, memory.remember, memory.about, etc.).
+Memory operations use MCP tools from the claudia-memory daemon (memory_recall, memory_remember, memory_about, etc.).
 The daemon provides ~33 tools for semantic search, pattern detection, and relationship tracking.
 See the memory-manager skill for the full tool reference.`;
     } catch {

package/bin/manifest-lib.js

@@ -0,0 +1,245 @@
+// Manifest library: pure functions powering user-skill preservation on upgrade.
+//
+// Shipped with every Claudia release. bin/index.js imports from here for the
+// upgrade flow; the unit tests in test/manifest.test.js cover every exported
+// function.
+//
+// See the execution brief in the commit that introduced this file for the
+// full design (three-way merge via shipped manifest + batch prompt UX).
+
+import { createHash } from 'node:crypto';
+import {
+  readFileSync,
+  readdirSync,
+  statSync,
+  existsSync,
+} from 'node:fs';
+import { join, relative, sep, posix } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Scope rules — what the manifest tracks.
+// Only files matching TRACK_PREFIXES (or the exact file CLAUDE.md) are
+// included. Anything matching EXCLUDE_PATTERNS is filtered out.
+// ---------------------------------------------------------------------------
+
+const TRACK_PREFIXES = [
+  '.claude/skills/',
+  '.claude/rules/',
+];
+
+const TRACKED_ROOT_FILES = new Set([
+  'CLAUDE.md',
+]);
+
+const EXCLUDE_SEGMENTS = [
+  '.claude/hooks/',
+  '.claude/agents/',
+  '.claude/commands/',
+  'workspaces/',
+  'node_modules/',
+];
+
+const EXCLUDE_BASENAMES = new Set([
+  'settings.local.json',
+  'manifest.json',
+  '.DS_Store',
+]);
+
+function isTrackedPath(relPosixPath) {
+  if (EXCLUDE_BASENAMES.has(relPosixPath.split('/').pop())) return false;
+  for (const seg of EXCLUDE_SEGMENTS) {
+    if (relPosixPath.startsWith(seg)) return false;
+  }
+  if (TRACKED_ROOT_FILES.has(relPosixPath)) return true;
+  for (const prefix of TRACK_PREFIXES) {
+    if (relPosixPath.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// hashFile — SHA-256 hex over raw bytes.
+// ---------------------------------------------------------------------------
+
+export function hashFile(absPath) {
+  const bytes = readFileSync(absPath);
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// walkFiles — recursive directory walk yielding posix-style relative paths.
+// ---------------------------------------------------------------------------
+
+function walkFiles(rootDir) {
+  const out = [];
+  function recurse(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        recurse(full);
+      } else if (entry.isFile()) {
+        out.push(full);
+      }
+    }
+  }
+  recurse(rootDir);
+  return out;
+}
+
+function toPosixRel(rootDir, absPath) {
+  return relative(rootDir, absPath).split(sep).join(posix.sep);
+}
+
+// ---------------------------------------------------------------------------
+// generateManifest — hashes every tracked file under rootDir.
+// ---------------------------------------------------------------------------
+
+export function generateManifest(rootDir, { version = 'unknown' } = {}) {
+  const files = {};
+  for (const abs of walkFiles(rootDir)) {
+    const relPosix = toPosixRel(rootDir, abs);
+    if (!isTrackedPath(relPosix)) continue;
+    files[relPosix] = hashFile(abs);
+  }
+  return {
+    version,
+    generated: new Date().toISOString(),
+    algorithm: 'sha256',
+    files,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// detectConflicts — three-way merge between old shipped, new shipped, and
+// the user's current files.
+// ---------------------------------------------------------------------------
+
+function safeManifestFiles(manifest) {
+  if (!manifest || typeof manifest !== 'object') return null;
+  if (!manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)) {
+    return null;
+  }
+  return manifest.files;
+}
+
+export function detectConflicts({ userDir, templateDir, oldManifest, newManifest }) {
+  const conflicts = [];
+  const userModifiedOnly = [];
+  const templateChangedOnly = [];
+  const unchanged = [];
+
+  const newFiles = safeManifestFiles(newManifest) || {};
+  const oldFiles = safeManifestFiles(oldManifest); // may be null
+
+  for (const relPath of Object.keys(newFiles)) {
+    const newHash = newFiles[relPath];
+    const userAbs = join(userDir, ...relPath.split('/'));
+
+    // File doesn't exist in user dir → not a conflict, the normal copy will create it
+    if (!existsSync(userAbs)) continue;
+
+    let userHash;
+    try {
+      userHash = hashFile(userAbs);
+    } catch {
+      // Unreadable file → skip, let the normal copy handle it
+      continue;
+    }
+
+    if (oldFiles && typeof oldFiles[relPath] === 'string') {
+      const oldHash = oldFiles[relPath];
+      const userDiffers = userHash !== oldHash;
+      const templateDiffers = newHash !== oldHash;
+
+      if (!userDiffers && !templateDiffers) {
+        unchanged.push(relPath);
+      } else if (!userDiffers && templateDiffers) {
+        templateChangedOnly.push(relPath);
+      } else if (userDiffers && !templateDiffers) {
+        userModifiedOnly.push(relPath);
+      } else {
+        // both changed
+        if (userHash === newHash) {
+          // User happened to edit to the new value — no conflict
+          unchanged.push(relPath);
+        } else {
+          conflicts.push(relPath);
+        }
+      }
+    } else {
+      // No prior manifest entry — fall back to direct compare against new template
+      if (userHash === newHash) {
+        unchanged.push(relPath);
+      } else {
+        conflicts.push(relPath);
+      }
+    }
+  }
+
+  return { conflicts, userModifiedOnly, templateChangedOnly, unchanged };
+}
+
+// ---------------------------------------------------------------------------
+// resolveBakPath — returns a .bak path that doesn't collide.
+// ---------------------------------------------------------------------------
+
+export function resolveBakPath(absPath) {
+  const base = absPath + '.bak';
+  if (!existsSync(base)) return base;
+  let n = 1;
+  while (existsSync(base + '.' + n)) n++;
+  return base + '.' + n;
+}
+
+// ---------------------------------------------------------------------------
+// applyResolution — turns a user choice into explicit skip/overwrite lists.
+// Pure: no filesystem side effects. Wraps the decision for unit testing.
+// ---------------------------------------------------------------------------
+
+export function applyResolution(conflicts, { choice, perFile } = {}) {
+  if (choice === 'cancel') {
+    return { skip: [], overwrite: [], cancelled: true };
+  }
+  if (choice === 'keep-all') {
+    return { skip: [...conflicts], overwrite: [], cancelled: false };
+  }
+  if (choice === 'overwrite-all') {
+    return { skip: [], overwrite: [...conflicts], cancelled: false };
+  }
+  if (choice === 'per-file') {
+    const skip = [];
+    const overwrite = [];
+    for (const f of conflicts) {
+      const answer = (perFile && perFile[f]) || 'keep';
+      if (answer === 'overwrite') overwrite.push(f);
+      else skip.push(f);
+    }
+    return { skip, overwrite, cancelled: false };
+  }
+  // Unknown choice → fail safe: keep user versions
+  return { skip: [...conflicts], overwrite: [], cancelled: false };
+}
+
+// ---------------------------------------------------------------------------
+// loadManifest — safe JSON load that returns null on any failure.
+// Used by bin/index.js to read the user's existing manifest.
+// ---------------------------------------------------------------------------
+
+export function loadManifest(absPath) {
+  try {
+    if (!existsSync(absPath)) return null;
+    const raw = readFileSync(absPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!safeManifestFiles(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}

package/memory-daemon/claudia_memory/daemon/health.py

@@ -290,7 +290,7 @@ class HealthCheckHandler(BaseHTTPRequestHandler):
             self.send_error(500, str(e))
 
     def _send_briefing_response(self):
-        """Send compact session briefing (same data as memory.briefing MCP tool).
+        """Send compact session briefing (same data as memory_briefing MCP tool).
 
         Lets session hooks call briefing data over HTTP before MCP tools register,
         providing a pre-MCP layer in the fallback chain.

package/memory-daemon/claudia_memory/daemon/scheduler.py

@@ -31,7 +31,7 @@ logger = logging.getLogger(__name__)
 RELEVANT_TOOL_PREFIXES = {
     "gmail", "google_workspace", "slack", "telegram",
     "SLACK_", "GMAIL_", "NOTION_", "CALENDAR_",
-    "memory.file", "memory.remember",
+    "memory_file", "memory_remember",
 }
 
 COMMITMENT_RE = re.compile(