The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: port continuous-learning observer fixes
Affaan Mustafa12e1bc424db4
diff --git a/scripts/hooks/session-start.js b/scripts/hooks/session-start.jsindex 3994d9c27..7b5192dc7 100644--- a/scripts/hooks/session-start.js+++ b/scripts/hooks/session-start.js@@ -10,7 +10,6 @@*/const {- getClaudeDir,getSessionsDir,getSessionSearchDirs,getLearnedSkillsDir,@@ -21,7 +20,7 @@ const {stripAnsi,log} = require('../lib/utils');-const { resolveProjectContext, writeSessionLease, resolveSessionId } = require('../lib/observer-sessions');+const { resolveProjectContext, writeSessionLease, resolveSessionId, getHomunculusDir } = require('../lib/observer-sessions');const { getPackageManager, getSelectionPrompt } = require('../lib/package-manager');const { listAliases } = require('../lib/session-aliases');const { detectProjectType } = require('../lib/project-detect');@@ -325,7 +324,7 @@ function extractInstinctAction(content) {}function summarizeActiveInstincts(observerContext) {- const homunculusDir = path.join(getClaudeDir(), 'homunculus');+ const homunculusDir = getHomunculusDir();const globalDirs = [{ dir: path.join(homunculusDir, 'instincts', 'personal'), scope: 'global' },{ dir: path.join(homunculusDir, 'instincts', 'inherited'), scope: 'global' },diff --git a/scripts/lib/observer-sessions.js b/scripts/lib/observer-sessions.jsindex 44742a3c8..08296da3a 100644--- a/scripts/lib/observer-sessions.js+++ b/scripts/lib/observer-sessions.js@@ -1,11 +1,28 @@const fs = require('fs');+const os = require('os');const path = require('path');const crypto = require('crypto');const { spawnSync } = require('child_process');-const { getClaudeDir, ensureDir, sanitizeSessionId } = require('./utils');+const { ensureDir, sanitizeSessionId } = require('./utils');function getHomunculusDir() {- return path.join(getClaudeDir(), 'homunculus');+ const override = process.env.CLV2_HOMUNCULUS_DIR;+ if (override) {+ if (path.isAbsolute(override)) {+ return override;+ }+ process.stderr.write(`[ecc] CLV2_HOMUNCULUS_DIR=${override} is not absolute; ignoring\n`);+ }++ const xdgDataHome = process.env.XDG_DATA_HOME;+ if (xdgDataHome) {+ if (path.isAbsolute(xdgDataHome)) {+ return path.join(xdgDataHome, 'ecc-homunculus');+ }+ process.stderr.write(`[ecc] XDG_DATA_HOME=${xdgDataHome} is not absolute; ignoring\n`);+ }++ return path.join(os.homedir(), '.local', 'share', 'ecc-homunculus');}function getProjectsDir() {@@ -39,6 +56,23 @@ function stripRemoteCredentials(remoteUrl) {return String(remoteUrl).replace(/:\/\/[^@]+@/, '://');}+function normalizeRemoteUrl(remoteUrl) {+ if (!remoteUrl) return '';+ const raw = String(remoteUrl);+ const isNetwork = !raw.startsWith('file://') && (raw.includes('://') || /^[^@/:]+@[^:/]+:/.test(raw));+ let normalized = stripRemoteCredentials(raw)+ .replace(/^[A-Za-z][A-Za-z0-9+.-]*:\/\//, '')+ .replace(/^[^@/:]+@([^:/]+):/, '$1/')+ .replace(/\.git\/?$/, '')+ .replace(/\/+$/, '');++ if (isNetwork) {+ normalized = normalized.toLowerCase();+ }++ return normalized;+}+function resolveProjectRoot(cwd = process.cwd()) {const envRoot = process.env.CLAUDE_PROJECT_DIR;if (envRoot && fs.existsSync(envRoot)) {@@ -53,7 +87,8 @@ function resolveProjectRoot(cwd = process.cwd()) {function computeProjectId(projectRoot) {const remoteUrl = stripRemoteCredentials(runGit(['remote', 'get-url', 'origin'], projectRoot));- return crypto.createHash('sha256').update(remoteUrl || projectRoot).digest('hex').slice(0, 12);+ const hashInput = normalizeRemoteUrl(remoteUrl) || remoteUrl || projectRoot;+ return crypto.createHash('sha256').update(hashInput).digest('hex').slice(0, 12);}function resolveProjectContext(cwd = process.cwd()) {@@ -163,6 +198,8 @@ function stopObserverForContext(context) {}module.exports = {+ getHomunculusDir,+ normalizeRemoteUrl,resolveProjectContext,getObserverActivityFile,getObserverPidFile,diff --git a/skills/continuous-learning-v2/SKILL.md b/skills/continuous-learning-v2/SKILL.mdindex 5153a2aa6..5604ed275 100644--- a/skills/continuous-learning-v2/SKILL.md+++ b/skills/continuous-learning-v2/SKILL.md@@ -26,7 +26,7 @@ An advanced learning system that turns your Claude Code sessions into reusable k| Feature | v2.0 | v2.1 ||---------|------|------|-| Storage | Global (~/.claude/homunculus/) | Project-scoped (projects/<hash>/) |+| Storage | Global (`~/.claude/homunculus/`) | Project-scoped (`${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<hash>/`) || Scope | All instincts apply everywhere | Project-scoped + global || Detection | None | git remote URL / repo path || Promotion | N/A | Project → global when seen in 2+ projects |@@ -132,7 +132,21 @@ The system automatically detects your current project:3. **`git rev-parse --show-toplevel`** -- fallback using repo path (machine-specific)4. **Global fallback** -- if no project is detected, instincts go to global scope-Each project gets a 12-character hash ID (e.g., `a1b2c3d4e5f6`). A registry file at `~/.claude/homunculus/projects.json` maps IDs to human-readable names.+Each project gets a 12-character hash ID (e.g., `a1b2c3d4e5f6`). A registry file at `${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json` maps IDs to human-readable names.++### Data Directory++Continuous-learning-v2 stores observer data outside `~/.claude` so Claude Code's sensitive-path guard does not block background instinct writes:++1. `CLV2_HOMUNCULUS_DIR` when set to an absolute path+2. `$XDG_DATA_HOME/ecc-homunculus`+3. `$HOME/.local/share/ecc-homunculus`++Existing users with data at `~/.claude/homunculus` can migrate once:++```bash+bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh+```## Quick Start@@ -173,7 +187,7 @@ The system creates directories automatically on first use, but you can also crea```bash# Global directories-mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}+mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/ecc-homunculus"/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}# Project directories are auto-created when the hook first runs in a git repo```@@ -226,7 +240,7 @@ Other behavior (observation capture, instinct thresholds, project scoping, promo## File Structure```-~/.claude/homunculus/+${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/+-- identity.json # Your profile, technical level+-- projects.json # Registry: project hash -> name/path/remote+-- observations.jsonl # Global observations (fallback)@@ -322,7 +336,7 @@ Hooks fire **100% of the time**, deterministically. This means:## Backward Compatibilityv2.1 is fully compatible with v2.0 and v1:-- Existing global instincts in `~/.claude/homunculus/instincts/` still work as global instincts+- Existing global instincts can be migrated from `~/.claude/homunculus/instincts/` with `scripts/migrate-homunculus.sh`- Existing `~/.claude/skills/learned/` skills from v1 still work- Stop hook still runs (but now also feeds into v2)- Gradual migration: run both in paralleldiff --git a/skills/continuous-learning-v2/agents/observer-loop.sh b/skills/continuous-learning-v2/agents/observer-loop.shindex f18d8ae55..a899124a1 100755--- a/skills/continuous-learning-v2/agents/observer-loop.sh+++ b/skills/continuous-learning-v2/agents/observer-loop.sh@@ -10,6 +10,7 @@ unset CLAUDECODESLEEP_PID=""USR1_FIRED=0+PENDING_ANALYSIS=0ANALYZING=0LAST_ANALYSIS_EPOCH=0# Minimum seconds between analyses (prevents rapid re-triggering)@@ -258,14 +259,17 @@ PROMPTon_usr1() {[ -n "$SLEEP_PID" ] && kill "$SLEEP_PID" 2>/dev/nullSLEEP_PID=""- USR1_FIRED=1- # Re-entrancy guard: skip if analysis is already running (#521)+ # Re-entrancy guard: defer the nudge so the main loop runs a follow-up+ # analysis immediately after the current analysis finishes.if [ "$ANALYZING" -eq 1 ]; then- echo "[$(date)] Analysis already in progress, skipping signal" >> "$LOG_FILE"+ PENDING_ANALYSIS=1+ echo "[$(date)] Analysis already in progress, deferring signal" >> "$LOG_FILE"returnfi+ USR1_FIRED=1+# Cooldown: skip if last analysis was too recent (#521)now_epoch=$(date +%s)elapsed=$(( now_epoch - LAST_ANALYSIS_EPOCH ))@@ -290,6 +294,17 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"while true; doexit_if_idle_without_sessions++ if [ "$PENDING_ANALYSIS" -eq 1 ]; then+ PENDING_ANALYSIS=0+ USR1_FIRED=0+ ANALYZING=1+ analyze_observations+ LAST_ANALYSIS_EPOCH=$(date +%s)+ ANALYZING=0+ continue+ fi+sleep "$OBSERVER_INTERVAL_SECONDS" &SLEEP_PID=$!wait "$SLEEP_PID" 2>/dev/null@@ -299,6 +314,9 @@ while true; doif [ "$USR1_FIRED" -eq 1 ]; thenUSR1_FIRED=0else+ ANALYZING=1analyze_observations+ LAST_ANALYSIS_EPOCH=$(date +%s)+ ANALYZING=0fidonediff --git a/skills/continuous-learning-v2/agents/observer.md b/skills/continuous-learning-v2/agents/observer.mdindex f00626887..e03845e5d 100644--- a/skills/continuous-learning-v2/agents/observer.md+++ b/skills/continuous-learning-v2/agents/observer.md@@ -17,8 +17,8 @@ A background agent that analyzes observations from Claude Code sessions to detec## InputReads observations from the **project-scoped** observations file:-- Project: `~/.claude/homunculus/projects/<project-hash>/observations.jsonl`-- Global fallback: `~/.claude/homunculus/observations.jsonl`+- Project: `${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<project-hash>/observations.jsonl`+- Global fallback: `${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/observations.jsonl````jsonl{"timestamp":"2025-01-22T10:30:00Z","event":"tool_start","session":"abc123","tool":"Edit","input":"...","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}@@ -66,8 +66,8 @@ When certain tools are consistently preferred:## OutputCreates/updates instincts in the **project-scoped** instincts directory:-- Project: `~/.claude/homunculus/projects/<project-hash>/instincts/personal/`-- Global: `~/.claude/homunculus/instincts/personal/` (for universal patterns)+- Project: `${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<project-hash>/instincts/personal/`+- Global: `${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/instincts/personal/` (for universal patterns)### Project-Scoped Instinct (default)diff --git a/skills/continuous-learning-v2/agents/start-observer.sh b/skills/continuous-learning-v2/agents/start-observer.shindex e9418a5c8..c3ada3140 100755--- a/skills/continuous-learning-v2/agents/start-observer.sh+++ b/skills/continuous-learning-v2/agents/start-observer.sh@@ -35,9 +35,13 @@ PYTHON_CMD="${CLV2_PYTHON_CMD:-}"# Configuration# ─────────────────────────────────────────────-CONFIG_DIR="${HOME}/.claude/homunculus"+# shellcheck disable=SC1091+. "${SKILL_ROOT}/scripts/lib/homunculus-dir.sh"+CONFIG_DIR="$(_ecc_resolve_homunculus_dir)"if [ -n "${CLV2_CONFIG:-}" ]; thenCONFIG_FILE="$CLV2_CONFIG"+elif [ -f "${CONFIG_DIR}/config.json" ]; then+ CONFIG_FILE="${CONFIG_DIR}/config.json"elseCONFIG_FILE="${SKILL_ROOT}/config.json"fidiff --git a/skills/continuous-learning-v2/hooks/observe.sh b/skills/continuous-learning-v2/hooks/observe.shindex 9ed6cf8bf..6631f7022 100755--- a/skills/continuous-learning-v2/hooks/observe.sh+++ b/skills/continuous-learning-v2/hooks/observe.sh@@ -115,7 +115,9 @@ fi# Sourcing detect-project.sh creates project-scoped directories and updates# projects.json, so automated sessions must return before that point.-CONFIG_DIR="${HOME}/.claude/homunculus"+# shellcheck disable=SC1091+. "$(dirname "$0")/../scripts/lib/homunculus-dir.sh"+CONFIG_DIR="$(_ecc_resolve_homunculus_dir)"# Skip if disabled (check both default and CLV2_CONFIG-derived locations)if [ -f "$CONFIG_DIR/disabled" ]; then@@ -344,10 +346,12 @@ if [ -f "${CONFIG_DIR}/disabled" ]; thenOBSERVER_ENABLED=falseelseOBSERVER_ENABLED=false- CONFIG_FILE="${SKILL_ROOT}/config.json"- # Allow CLV2_CONFIG overrideif [ -n "${CLV2_CONFIG:-}" ]; thenCONFIG_FILE="$CLV2_CONFIG"+ elif [ -f "${CONFIG_DIR}/config.json" ]; then+ CONFIG_FILE="${CONFIG_DIR}/config.json"+ else+ CONFIG_FILE="${SKILL_ROOT}/config.json"fi# Use effective config path for both existence check and readingEFFECTIVE_CONFIG="$CONFIG_FILE"diff --git a/skills/continuous-learning-v2/scripts/detect-project.sh b/skills/continuous-learning-v2/scripts/detect-project.shindex 8cf1be2dd..66e541c41 100755--- a/skills/continuous-learning-v2/scripts/detect-project.sh+++ b/skills/continuous-learning-v2/scripts/detect-project.sh@@ -19,7 +19,9 @@# 3. git repo root path (fallback, machine-specific)# 4. "global" (no project context detected)-_CLV2_HOMUNCULUS_DIR="${HOME}/.claude/homunculus"+# shellcheck disable=SC1091+. "$(dirname "${BASH_SOURCE[0]}")/lib/homunculus-dir.sh"+_CLV2_HOMUNCULUS_DIR="$(_ecc_resolve_homunculus_dir)"_CLV2_PROJECTS_DIR="${_CLV2_HOMUNCULUS_DIR}/projects"_CLV2_REGISTRY_FILE="${_CLV2_HOMUNCULUS_DIR}/projects.json"@@ -49,6 +51,30 @@ export CLV2_PYTHON_CMDCLV2_OBSERVER_PROMPT_PATTERN='Can you confirm|requires permission|Awaiting (user confirmation|confirmation|approval|permission)|confirm I should proceed|once granted access|grant.*access'export CLV2_OBSERVER_PROMPT_PATTERN+_clv2_normalize_remote_url() {+ local url="$1"+ [ -z "$url" ] && return 0++ local is_network=0+ case "$url" in+ file://*) is_network=0 ;;+ *://*) is_network=1 ;;+ *@*:*) is_network=1 ;;+ *) is_network=0 ;;+ esac++ url=$(printf '%s' "$url" | sed -E 's|://[^@]+@|://|')+ url=$(printf '%s' "$url" | sed -E 's|^[A-Za-z][A-Za-z0-9+.-]*://||')+ url=$(printf '%s' "$url" | sed -E 's|^[^@/:]+@([^:/]+):|\1/|')+ url=$(printf '%s' "$url" | sed -E 's|\.git/?$||; s|/+$||')++ if [ "$is_network" = "1" ]; then+ printf '%s' "$url" | tr '[:upper:]' '[:lower:]'+ else+ printf '%s' "$url"+ fi+}+_clv2_detect_project() {local project_root=""local project_name=""@@ -94,15 +120,20 @@ _clv2_detect_project() {fifi- # Compute hash from the original remote URL (legacy, for backward compatibility)- local legacy_hash_input="${remote_url:-$project_root}"+ local raw_remote_url="$remote_url"# Strip embedded credentials from remote URL (e.g., https://[email protected]/...)if [ -n "$remote_url" ]; thenremote_url=$(printf '%s' "$remote_url" | sed -E 's|://[^@]+@|://|')fi- local hash_input="${remote_url:-$project_root}"+ local legacy_hash_input="${remote_url:-$project_root}"+ local normalized_remote=""+ if [ -n "$remote_url" ]; then+ normalized_remote=$(_clv2_normalize_remote_url "$remote_url")+ fi++ local hash_input="${normalized_remote:-${remote_url:-$project_root}}"# Prefer Python for consistent SHA256 behavior across shells/platforms.# Pass the value via env var and encode as UTF-8 inside Python so the hash# is locale-independent (shells vary between UTF-8 / CP932 / CP1252, which@@ -122,19 +153,33 @@ print(hashlib.sha256(s.encode("utf-8")).hexdigest()[:12])echo "fallback")fi- # Backward compatibility: if credentials were stripped and the hash changed,- # check if a project dir exists under the legacy hash and reuse it- if [ "$legacy_hash_input" != "$hash_input" ] && [ -n "$_CLV2_PYTHON_CMD" ]; then- local legacy_id=""- legacy_id=$(_CLV2_HASH_INPUT="$legacy_hash_input" "$_CLV2_PYTHON_CMD" -c '+ # Backward compatibility: migrate a single legacy project directory from+ # credential-stripped or raw remote hashes to the normalized remote hash.+ if [ -n "$_CLV2_PYTHON_CMD" ] && [ ! -d "${_CLV2_PROJECTS_DIR}/${project_id}" ]; then+ local legacy_inputs=()+ [ -n "$legacy_hash_input" ] && [ "$legacy_hash_input" != "$hash_input" ] \+ && legacy_inputs+=("$legacy_hash_input")+ [ -n "$raw_remote_url" ] && [ "$raw_remote_url" != "$hash_input" ] \+ && [ "$raw_remote_url" != "$legacy_hash_input" ] \+ && legacy_inputs+=("$raw_remote_url")++ local legacy_input legacy_id+ for legacy_input in "${legacy_inputs[@]}"; do+ legacy_id=$(_CLV2_HASH_INPUT="$legacy_input" "$_CLV2_PYTHON_CMD" -c 'import os, hashlibs = os.environ["_CLV2_HASH_INPUT"]print(hashlib.sha256(s.encode("utf-8")).hexdigest()[:12])' 2>/dev/null)- if [ -n "$legacy_id" ] && [ -d "${_CLV2_PROJECTS_DIR}/${legacy_id}" ] && [ ! -d "${_CLV2_PROJECTS_DIR}/${project_id}" ]; then- # Migrate legacy directory to new hash- mv "${_CLV2_PROJECTS_DIR}/${legacy_id}" "${_CLV2_PROJECTS_DIR}/${project_id}" 2>/dev/null || project_id="$legacy_id"- fi+ if [ -n "$legacy_id" ] && [ "$legacy_id" != "$project_id" ] \+ && [ -d "${_CLV2_PROJECTS_DIR}/${legacy_id}" ]; then+ if mv "${_CLV2_PROJECTS_DIR}/${legacy_id}" "${_CLV2_PROJECTS_DIR}/${project_id}" 2>/dev/null; then+ break+ else+ project_id="$legacy_id"+ break+ fi+ fi+ donefi# Export resultsdiff --git a/skills/continuous-learning-v2/scripts/instinct-cli.py b/skills/continuous-learning-v2/scripts/instinct-cli.pyindex 22cfc968e..e56114245 100755--- a/skills/continuous-learning-v2/scripts/instinct-cli.py+++ b/skills/continuous-learning-v2/scripts/instinct-cli.py@@ -38,7 +38,48 @@ except ImportError:# Configuration# ─────────────────────────────────────────────-HOMUNCULUS_DIR = Path.home() / ".claude" / "homunculus"+def _resolve_homunculus_dir() -> Path:+ override = os.environ.get("CLV2_HOMUNCULUS_DIR")+ if override:+ if Path(override).is_absolute():+ return Path(override)+ print(f"[ecc] CLV2_HOMUNCULUS_DIR={override!r} is not absolute; ignoring", file=sys.stderr)++ xdg = os.environ.get("XDG_DATA_HOME")+ if xdg:+ if Path(xdg).is_absolute():+ return Path(xdg) / "ecc-homunculus"+ print(f"[ecc] XDG_DATA_HOME={xdg!r} is not absolute; ignoring", file=sys.stderr)++ return Path.home() / ".local" / "share" / "ecc-homunculus"+++def _strip_remote_credentials(remote_url: str) -> str:+ return re.sub(r"://[^@]+@", "://", remote_url or "")+++def _normalize_remote_url(remote_url: str) -> str:+ if not remote_url:+ return ""++ is_network = (+ not remote_url.startswith("file://")+ and ("://" in remote_url or re.match(r"^[^@/:]+@[^:/]+:", remote_url) is not None)+ )+ normalized = _strip_remote_credentials(remote_url)+ normalized = re.sub(r"^[A-Za-z][A-Za-z0-9+.-]*://", "", normalized)+ normalized = re.sub(r"^[^@/:]+@([^:/]+):", r"\1/", normalized)+ normalized = re.sub(r"\.git/?$", "", normalized)+ normalized = re.sub(r"/+$", "", normalized)++ return normalized.lower() if is_network else normalized+++def _project_hash(value: str) -> str:+ return hashlib.sha256(value.encode("utf-8")).hexdigest()[:12]+++HOMUNCULUS_DIR = _resolve_homunculus_dir()PROJECTS_DIR = HOMUNCULUS_DIR / "projects"REGISTRY_FILE = HOMUNCULUS_DIR / "projects.json"@@ -177,11 +218,35 @@ def detect_project() -> dict:except (subprocess.TimeoutExpired, FileNotFoundError):pass- hash_source = remote_url if remote_url else project_root- project_id = hashlib.sha256(hash_source.encode()).hexdigest()[:12]+ raw_remote_url = remote_url+ if remote_url:+ remote_url = _strip_remote_credentials(remote_url)++ legacy_hash_source = remote_url if remote_url else project_root+ normalized_remote = _normalize_remote_url(remote_url) if remote_url else ""+ hash_source = normalized_remote if normalized_remote else legacy_hash_source+ project_id = _project_hash(hash_source)project_dir = PROJECTS_DIR / project_id+ if not project_dir.exists():+ legacy_sources = []+ if legacy_hash_source and legacy_hash_source != hash_source:+ legacy_sources.append(legacy_hash_source)+ if raw_remote_url and raw_remote_url not in {hash_source, legacy_hash_source}:+ legacy_sources.append(raw_remote_url)++ for legacy_source in legacy_sources:+ legacy_id = _project_hash(legacy_source)+ legacy_dir = PROJECTS_DIR / legacy_id+ if legacy_id != project_id and legacy_dir.exists():+ try:+ legacy_dir.rename(project_dir)+ except OSError:+ project_id = legacy_id+ project_dir = legacy_dir+ break+# Ensure project directory structurefor d in [project_dir / "instincts" / "personal",diff --git a/skills/continuous-learning-v2/scripts/lib/homunculus-dir.sh b/skills/continuous-learning-v2/scripts/lib/homunculus-dir.shnew file mode 100644index 000000000..9f1e926a7--- /dev/null+++ b/skills/continuous-learning-v2/scripts/lib/homunculus-dir.sh@@ -0,0 +1,31 @@+#!/usr/bin/env bash+# Shared continuous-learning-v2 data-directory resolver.+#+# Resolution precedence:+# 1. CLV2_HOMUNCULUS_DIR, when absolute+# 2. XDG_DATA_HOME/ecc-homunculus, when XDG_DATA_HOME is absolute+# 3. HOME/.local/share/ecc-homunculus++_ecc_resolve_homunculus_dir() {+ if [ -n "${CLV2_HOMUNCULUS_DIR:-}" ]; then+ case "$CLV2_HOMUNCULUS_DIR" in+ /*) printf '%s\n' "$CLV2_HOMUNCULUS_DIR"; return 0 ;;+ *) printf '[ecc] CLV2_HOMUNCULUS_DIR=%s is not absolute; ignoring\n' "$CLV2_HOMUNCULUS_DIR" >&2 ;;+ esac+ fi++ if [ -n "${XDG_DATA_HOME:-}" ]; then+ case "$XDG_DATA_HOME" in+ /*) printf '%s/ecc-homunculus\n' "$XDG_DATA_HOME"; return 0 ;;+ *) printf '[ecc] XDG_DATA_HOME=%s is not absolute; ignoring\n' "$XDG_DATA_HOME" >&2 ;;+ esac+ fi++ case "${HOME:-}" in+ /*) printf '%s/.local/share/ecc-homunculus\n' "$HOME" ;;+ *)+ printf '[ecc] HOME=%s is not absolute; cannot resolve homunculus dir\n' "${HOME:-}" >&2+ return 1+ ;;+ esac+}diff --git a/skills/continuous-learning-v2/scripts/migrate-homunculus.sh b/skills/continuous-learning-v2/scripts/migrate-homunculus.shnew file mode 100755index 000000000..9358fc7b4--- /dev/null+++ b/skills/continuous-learning-v2/scripts/migrate-homunculus.sh@@ -0,0 +1,62 @@+#!/usr/bin/env bash+# One-shot migration from the legacy Claude config tree into the+# continuous-learning-v2 data directory.+set -euo pipefail++OLD="${HOME}/.claude/homunculus"++# shellcheck disable=SC1091+. "$(dirname "$0")/lib/homunculus-dir.sh"+NEW="$(_ecc_resolve_homunculus_dir)"++if [ "$NEW" = "$OLD" ]; then+ echo "Resolved destination equals source ($OLD); nothing to migrate."+ exit 0+fi++if [ ! -d "$OLD" ]; then+ echo "Nothing to migrate (no $OLD)."+ exit 0+fi++if command -v pgrep >/dev/null 2>&1; then+ if pgrep -f "${HOME}.*observer-loop\\.sh" >/dev/null 2>&1; then+ echo "Refusing to migrate: observer-loop.sh is running." >&2+ echo "Exit all Claude Code sessions, then re-run." >&2+ exit 1+ fi+else+ echo "Warning: pgrep not available; skipping running-observer check." >&2+fi++mkdir -p "$(dirname "$NEW")"++if [ ! -d "$NEW" ]; then+ mv "$OLD" "$NEW"+ echo "Moved $OLD -> $NEW"+elif [ -z "$(ls -A "$NEW" 2>/dev/null || true)" ]; then+ rmdir "$NEW"+ mv "$OLD" "$NEW"+ echo "Moved $OLD -> $NEW (replaced empty destination)"+else+ old_count="$(find "$OLD" -type f 2>/dev/null | wc -l | tr -d ' ')"+ new_count="$(find "$NEW" -type f 2>/dev/null | wc -l | tr -d ' ')"+ echo "Refusing to migrate: both paths exist with content." >&2+ echo " Old: $OLD ($old_count files)" >&2+ echo " New: $NEW ($new_count files)" >&2+ echo "Resolve manually, then re-run." >&2+ exit 1+fi++settings="${HOME}/.claude/settings.json"+if [ -f "$settings" ] && grep -q '"CLV2_CONFIG"' "$settings" 2>/dev/null; then+ if grep -q '\.claude/homunculus' "$settings" 2>/dev/null; then+ cat >&2 <<WARN++Advisory: ~/.claude/settings.json still sets CLV2_CONFIG under the old path.+Update it to: ${NEW}/config.json+(Not editing settings.json automatically.)++WARN+ fi+fidiff --git a/skills/continuous-learning/SKILL.md b/skills/continuous-learning/SKILL.mdindex f56f549cd..1118ee3b1 100644--- a/skills/continuous-learning/SKILL.md+++ b/skills/continuous-learning/SKILL.md@@ -1,10 +1,18 @@---name: continuous-learning-description: Automatically extract reusable patterns from Claude Code sessions and save them as learned skills for future use.+description: "[DEPRECATED - use continuous-learning-v2] Legacy v1 stop-hook skill extractor. v2 is a strict superset with instinct-based, project-scoped, hook-reliable learning. Do not invoke v1; route continuous learning, session learning, and pattern extraction requests to continuous-learning-v2."origin: ECC----# Continuous Learning Skill+# Continuous Learning Skill - DEPRECATED++> **DEPRECATED 2026-04-28.** Use `continuous-learning-v2` instead. v2 is a strict superset: stop-hook observation becomes PreToolUse/PostToolUse observation, full skills become atomic instincts with confidence scoring, and global-only storage becomes project-scoped plus global promotion.+>+> This file is kept for archival reference and backward compatibility with existing installs.++---++## Original v1 Documentation (archival)Automatically evaluates Claude Code sessions on end to extract reusable patterns that can be saved as learned skills.diff --git a/tests/hooks/hooks.test.js b/tests/hooks/hooks.test.jsindex c5a6554e2..0142a876b 100644--- a/tests/hooks/hooks.test.js+++ b/tests/hooks/hooks.test.js@@ -248,7 +248,7 @@ function withPrependedPath(binDir, env = {}) {}function assertNoProjectDetectionSideEffects(homeDir, testName) {- const homunculusDir = path.join(homeDir, '.claude', 'homunculus');+ const homunculusDir = path.join(homeDir, '.local', 'share', 'ecc-homunculus');const registryPath = path.join(homunculusDir, 'projects.json');const projectsDir = path.join(homunculusDir, 'projects');@@ -2885,11 +2885,12 @@ async function runTests() {assert.strictEqual(code, 0, `detect-project should source cleanly, stderr: ${stderr}`);const [projectId, projectDir] = stdout.trim().split(/\r?\n/);- const registryPath = path.join(homeDir, '.claude', 'homunculus', 'projects.json');+ const registryPath = path.join(homeDir, '.local', 'share', 'ecc-homunculus', 'projects.json');const expectedProjectDir = path.join(homeDir,- '.claude',- 'homunculus',+ '.local',+ 'share',+ 'ecc-homunculus','projects',projectId);@@ -2963,7 +2964,7 @@ async function runTests() {assert.strictEqual(result.code, 0, `observe.sh should exit successfully, stderr: ${result.stderr}`);- const projectsDir = path.join(homeDir, '.claude', 'homunculus', 'projects');+ const projectsDir = path.join(homeDir, '.local', 'share', 'ecc-homunculus', 'projects');const projectIds = fs.readdirSync(projectsDir);assert.strictEqual(projectIds.length, 1, 'observe.sh should create one project-scoped observation directory');diff --git a/tests/hooks/observe-subdirectory-detection.test.js b/tests/hooks/observe-subdirectory-detection.test.jsindex 752586288..7a5723ffb 100644--- a/tests/hooks/observe-subdirectory-detection.test.js+++ b/tests/hooks/observe-subdirectory-detection.test.js@@ -112,7 +112,7 @@ function runObserve({ homeDir, cwd }) {}function readSingleProjectMetadata(homeDir) {- const projectsDir = path.join(homeDir, '.claude', 'homunculus', 'projects');+ const projectsDir = path.join(homeDir, '.local', 'share', 'ecc-homunculus', 'projects');const projectIds = fs.readdirSync(projectsDir);assert.strictEqual(projectIds.length, 1, 'Expected exactly one project directory');const projectDir = path.join(projectsDir, projectIds[0]);diff --git a/tests/hooks/observer-memory.test.js b/tests/hooks/observer-memory.test.jsindex 9436db67a..2857d208d 100644--- a/tests/hooks/observer-memory.test.js+++ b/tests/hooks/observer-memory.test.js@@ -96,7 +96,8 @@ test('observer-loop.sh defines ANALYZING guard variable', () => {test('on_usr1 checks ANALYZING before starting analysis', () => {const content = fs.readFileSync(observerLoopPath, 'utf8');assert.ok(content.includes('if [ "$ANALYZING" -eq 1 ]'), 'on_usr1 should check ANALYZING flag');- assert.ok(content.includes('Analysis already in progress, skipping signal'), 'on_usr1 should log when skipping due to re-entrancy');+ assert.ok(content.includes('Analysis already in progress, deferring signal'), 'on_usr1 should log when deferring due to re-entrancy');+ assert.ok(content.includes('PENDING_ANALYSIS=1'), 'on_usr1 should preserve re-entrant nudges for the next loop iteration');});test('on_usr1 sets ANALYZING=1 before and ANALYZING=0 after analysis', () => {@@ -110,6 +111,15 @@ test('on_usr1 sets ANALYZING=1 before and ANALYZING=0 after analysis', () => {assert.ok(analyzeReset > analyzeObsCall, 'ANALYZING=0 should follow analyze_observations');});+test('observer-loop checks pending analysis before sleeping', () => {+ const content = fs.readFileSync(observerLoopPath, 'utf8');+ assert.ok(/^PENDING_ANALYSIS=0$/m.test(content), 'PENDING_ANALYSIS should initialize to 0');+ assert.ok(+ /if \[ "\$PENDING_ANALYSIS" -eq 1 \]; then[\s\S]*?analyze_observations[\s\S]*?continue[\s\S]*?sleep "\$OBSERVER_INTERVAL_SECONDS"/.test(content),+ 'observer-loop should process deferred analysis before the interval sleep'+ );+});+// ──────────────────────────────────────────────────────// Test group 3: observer-loop.sh cooldown throttle// ──────────────────────────────────────────────────────@@ -334,8 +344,10 @@ test('observe.sh creates counter file and increments on each call', () => {// Create a minimal detect-project.sh that sets required varsconst skillRoot = path.join(testDir, 'skill');const scriptsDir = path.join(skillRoot, 'scripts');+ const scriptsLibDir = path.join(scriptsDir, 'lib');const hooksDir = path.join(skillRoot, 'hooks');fs.mkdirSync(scriptsDir, { recursive: true });+ fs.mkdirSync(scriptsLibDir, { recursive: true });fs.mkdirSync(hooksDir, { recursive: true });// Minimal detect-project.sh stub@@ -351,6 +363,14 @@ test('observe.sh creates counter file and increments on each call', () => {''].join('\n'));+ fs.writeFileSync(+ path.join(scriptsLibDir, 'homunculus-dir.sh'),+ [+ '#!/bin/bash',+ '_ecc_resolve_homunculus_dir() { printf "%s\\n" "$HOME/.local/share/ecc-homunculus"; }',+ ''+ ].join('\n')+ );// Copy observe.sh but patch SKILL_ROOT to our test dirlet observeContent = fs.readFileSync(observeShPath, 'utf8');diff --git a/tests/integration/hooks.test.js b/tests/integration/hooks.test.jsindex 7c4d06a2b..e05b4e492 100644--- a/tests/integration/hooks.test.js+++ b/tests/integration/hooks.test.js@@ -226,6 +226,15 @@ function cleanupTestDir(testDir) {fs.rmSync(testDir, { recursive: true, force: true });}+function getTestHomunculusEnv(testDir) {+ const xdgDataHome = path.join(testDir, '.local', 'share');+ return {+ HOME: testDir,+ XDG_DATA_HOME: xdgDataHome,+ homunculusDir: path.join(xdgDataHome, 'ecc-homunculus'),+ };+}+function writeInstinctFile(filePath, entries) {const body = entries.map(entry => `---id: ${entry.id}@@ -380,19 +389,20 @@ async function runTests() {try {const sessionId = `session-${Date.now()}`;+ const homunculusEnv = getTestHomunculusEnv(testDir);const result = await runHookWithInput(path.join(scriptsDir, 'session-start.js'),{},{- HOME: testDir,+ HOME: homunculusEnv.HOME,+ XDG_DATA_HOME: homunculusEnv.XDG_DATA_HOME,CLAUDE_PROJECT_DIR: projectDir,CLAUDE_SESSION_ID: sessionId});assert.strictEqual(result.code, 0, 'SessionStart should exit 0');- const homunculusDir = path.join(testDir, '.claude', 'homunculus');- const projectsDir = path.join(homunculusDir, 'projects');+ const projectsDir = path.join(homunculusEnv.homunculusDir, 'projects');const projectEntries = fs.existsSync(projectsDir) ? fs.readdirSync(projectsDir) : [];assert.ok(projectEntries.length > 0, 'SessionStart should create a homunculus project directory');const leaseDir = path.join(projectsDir, projectEntries[0], '.observer-sessions');@@ -410,7 +420,8 @@ async function runTests() {try {const projectId = crypto.createHash('sha256').update(projectDir).digest('hex').slice(0, 12);- const homunculusDir = path.join(testDir, '.claude', 'homunculus');+ const homunculusEnv = getTestHomunculusEnv(testDir);+ const homunculusDir = homunculusEnv.homunculusDir;const projectInstinctDir = path.join(homunculusDir, 'projects', projectId, 'instincts', 'personal');const globalInstinctDir = path.join(homunculusDir, 'instincts', 'inherited');@@ -445,7 +456,8 @@ async function runTests() {path.join(scriptsDir, 'session-start.js'),{},{- HOME: testDir,+ HOME: homunculusEnv.HOME,+ XDG_DATA_HOME: homunculusEnv.XDG_DATA_HOME,CLAUDE_PROJECT_DIR: projectDir,});@@ -474,18 +486,19 @@ async function runTests() {});try {+ const homunculusEnv = getTestHomunculusEnv(testDir);await runHookWithInput(path.join(scriptsDir, 'session-start.js'),{},{- HOME: testDir,+ HOME: homunculusEnv.HOME,+ XDG_DATA_HOME: homunculusEnv.XDG_DATA_HOME,CLAUDE_PROJECT_DIR: projectDir,CLAUDE_SESSION_ID: sessionId});- const homunculusDir = path.join(testDir, '.claude', 'homunculus');- const projectsDir = path.join(homunculusDir, 'projects');+ const projectsDir = path.join(homunculusEnv.homunculusDir, 'projects');const projectEntries = fs.existsSync(projectsDir) ? fs.readdirSync(projectsDir) : [];assert.ok(projectEntries.length > 0, 'Expected SessionStart to create a homunculus project directory');const projectStorageDir = path.join(projectsDir, projectEntries[0]);@@ -497,7 +510,8 @@ async function runTests() {path.join(scriptsDir, 'session-end-marker.js'),markerInput,{- HOME: testDir,+ HOME: homunculusEnv.HOME,+ XDG_DATA_HOME: homunculusEnv.XDG_DATA_HOME,CLAUDE_PROJECT_DIR: projectDir,CLAUDE_SESSION_ID: sessionId}diff --git a/tests/lib/observer-sessions.test.js b/tests/lib/observer-sessions.test.jsnew file mode 100644index 000000000..d9487e014--- /dev/null+++ b/tests/lib/observer-sessions.test.js@@ -0,0 +1,134 @@+const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');+const { spawnSync } = require('child_process');++const {+ getHomunculusDir,+ normalizeRemoteUrl,+ resolveProjectContext,+} = require('../../scripts/lib/observer-sessions');++let passed = 0;+let failed = 0;++function test(name, fn) {+ try {+ fn();+ console.log(` ✓ ${name}`);+ passed += 1;+ } catch (error) {+ console.log(` ✗ ${name}`);+ console.log(` ${error.message}`);+ failed += 1;+ }+}++function createTempDir() {+ return fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-observer-sessions-'));+}++function cleanup(dir) {+ try {+ fs.rmSync(dir, { recursive: true, force: true });+ } catch {+ // ignore cleanup errors+ }+}++function withEnv(overrides, fn) {+ const previous = {};+ for (const key of Object.keys(overrides)) {+ previous[key] = process.env[key];+ if (overrides[key] === undefined) {+ delete process.env[key];+ } else {+ process.env[key] = overrides[key];+ }+ }+ try {+ return fn();+ } finally {+ for (const [key, value] of Object.entries(previous)) {+ if (value === undefined) {+ delete process.env[key];+ } else {+ process.env[key] = value;+ }+ }+ }+}++function initRepo(repoDir, remoteUrl) {+ fs.mkdirSync(repoDir, { recursive: true });+ spawnSync('git', ['init'], { cwd: repoDir, stdio: 'ignore' });+ spawnSync('git', ['remote', 'add', 'origin', remoteUrl], { cwd: repoDir, stdio: 'ignore' });+}++console.log('\n=== observer-sessions tests ===\n');++test('getHomunculusDir prefers absolute CLV2_HOMUNCULUS_DIR', () => {+ const root = createTempDir();+ try {+ const override = path.join(root, 'custom-store');+ withEnv({ CLV2_HOMUNCULUS_DIR: override, XDG_DATA_HOME: path.join(root, 'xdg') }, () => {+ assert.strictEqual(getHomunculusDir(), override);+ });+ } finally {+ cleanup(root);+ }+});++test('getHomunculusDir ignores relative overrides and uses XDG_DATA_HOME', () => {+ const root = createTempDir();+ try {+ const xdg = path.join(root, 'xdg');+ withEnv({ CLV2_HOMUNCULUS_DIR: 'relative-store', XDG_DATA_HOME: xdg }, () => {+ assert.strictEqual(getHomunculusDir(), path.join(xdg, 'ecc-homunculus'));+ });+ } finally {+ cleanup(root);+ }+});++test('normalizeRemoteUrl collapses common network remote variants', () => {+ const expected = 'github.com/owner/repo';+ assert.strictEqual(normalizeRemoteUrl('[email protected]:Owner/Repo.git'), expected);+ assert.strictEqual(normalizeRemoteUrl('https://github.com/owner/repo.git'), expected);+ assert.strictEqual(normalizeRemoteUrl('ssh://[email protected]/Owner/Repo.git'), expected);+ assert.strictEqual(normalizeRemoteUrl('https://[email protected]/owner/repo.git'), expected);+});++test('normalizeRemoteUrl preserves local path case', () => {+ assert.strictEqual(normalizeRemoteUrl('/tmp/Repos/MyProject'), '/tmp/Repos/MyProject');+ assert.strictEqual(normalizeRemoteUrl('file:///tmp/Repos/MyProject.git'), '/tmp/Repos/MyProject');+});++test('resolveProjectContext gives SSH and HTTPS clones the same project id', () => {+ const root = createTempDir();+ try {+ const storage = path.join(root, 'store');+ const sshRepo = path.join(root, 'ssh-clone');+ const httpsRepo = path.join(root, 'https-clone');+ initRepo(sshRepo, '[email protected]:Owner/Repo.git');+ initRepo(httpsRepo, 'https://github.com/owner/repo.git');++ withEnv({+ CLV2_HOMUNCULUS_DIR: storage,+ XDG_DATA_HOME: undefined,+ CLAUDE_PROJECT_DIR: undefined,+ }, () => {+ const sshContext = resolveProjectContext(sshRepo);+ const httpsContext = resolveProjectContext(httpsRepo);+ assert.strictEqual(sshContext.projectId, httpsContext.projectId);+ assert.strictEqual(sshContext.projectDir, httpsContext.projectDir);+ });+ } finally {+ cleanup(root);+ }+});++console.log(`\nPassed: ${passed}`);+console.log(`Failed: ${failed}`);+process.exit(failed > 0 ? 1 : 0);