@heytherevibin/skillforge 0.2.1

package/skills/continuous-learning-v2/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: continuous-learning-v2
+description: Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. v2.1 adds project-scoped instincts to prevent cross-project contamination.
+origin: the toolset
+version: 2.1.0
+---
+
+# Continuous Learning v2.1 - Instinct
+-Based Architecture
+
+An advanced learning system that turns your Claude Code sessions into reusable knowledge through atomic "instincts" - small learned behaviors with confidence scoring.
+
+**v2.1** adds **project-scoped instincts** — React patterns stay in your React project, Python conventions stay in your Python project, and universal patterns (like "always validate input") are shared globally.
+
+## When to Activate
+
+- Setting up automatic learning from Claude Code sessions
+- Configuring instinct-based behavior extraction via hooks
+- Tuning confidence thresholds for learned behaviors
+- Reviewing, exporting, or importing instinct libraries
+- Evolving instincts into full skills, commands, or agents
+- Managing project-scoped vs global instincts
+- Promoting instincts from project to global scope
+
+## What's New in v2.1
+
+| Feature | v2.0 | v2.1 |
+|---------|------|------|
+| Storage | Global (`~/.claude/homunculus/`) | Project-scoped (`${XDG_DATA_HOME:-~/.local/share}/skill-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 |
+| Commands | 4 (status/evolve/export/import) | 6 (+promote/projects) |
+| Cross-project | Contamination risk | Isolated by default |
+
+## What's New in v2 (vs v1)
+
+| Feature | v1 | v2 |
+|---------|----|----|
+| Observation | Stop hook (session end) | PreToolUse/PostToolUse (100% reliable) |
+| Analysis | Main context | Background agent (Haiku) |
+| Granularity | Full skills | Atomic "instincts" |
+| Confidence | None | 0.3-0.9 weighted |
+| Evolution | Direct to skill | Instincts -> cluster -> skill/command/agent |
+| Sharing | None | Export/import instincts |
+
+## The Instinct Model
+
+An instinct is a small learned behavior:
+
+```yaml
+---
+id: prefer-functional-style
+trigger: "when writing new functions"
+confidence: 0.7
+domain: "code-style"
+source: "session-observation"
+scope: project
+project_id: "a1b2c3d4e5f6"
+project_name: "my-react-app"
+---
+
+# Prefer Functional Style
+
+## Action
+Use functional patterns over classes when appropriate.
+
+## Evidence
+- Observed 5 instances of functional pattern preference
+- User corrected class-based approach to functional on 2025-01-15
+```
+
+**Properties:**
+- **Atomic** -- one trigger, one action
+- **Confidence-weighted** -- 0.3 = tentative, 0.9 = near certain
+- **Domain-tagged** -- code-style, testing, git, debugging, workflow, etc.
+- **Evidence-backed** -- tracks what observations created it
+- **Scope-aware** -- `project` (default) or `global`
+
+## How It Works
+
+```
+Session Activity (in a git repo)
+      |
+      | Hooks capture prompts + tool use (100% reliable)
+      | + detect project context (git remote / repo path)
+      v
++---------------------------------------------+
+|  projects/<project-hash>/observations.jsonl  |
+|   (prompts, tool calls, outcomes, project)   |
++---------------------------------------------+
+      |
+      | Observer agent reads (background, Haiku)
+      v
++---------------------------------------------+
+|          PATTERN DETECTION                   |
+|   * User corrections -> instinct             |
+|   * Error resolutions -> instinct            |
+|   * Repeated workflows -> instinct           |
+|   * Scope decision: project or global?       |
++---------------------------------------------+
+      |
+      | Creates/updates
+      v
++---------------------------------------------+
+|  projects/<project-hash>/instincts/personal/ |
+|   * prefer-functional.yaml (0.7) [project]   |
+|   * use-react-hooks.yaml (0.9) [project]     |
++---------------------------------------------+
+|  instincts/personal/  (GLOBAL)               |
+|   * always-validate-input.yaml (0.85) [global]|
+|   * grep-before-edit.yaml (0.6) [global]     |
++---------------------------------------------+
+      |
+      | /evolve clusters + /promote
+      v
++---------------------------------------------+
+|  projects/<hash>/evolved/ (project-scoped)   |
+|  evolved/ (global)                           |
+|   * commands/new-feature.md                  |
+|   * skills/testing-workflow.md               |
+|   * agents/refactor-specialist.md            |
++---------------------------------------------+
+```
+
+## Project Detection
+
+The system automatically detects your current project:
+
+1. **`CLAUDE_PROJECT_DIR` env var** (highest priority)
+2. **`git remote get-url origin`** -- hashed to create a portable project ID (same repo on different machines gets the same ID)
+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 `${XDG_DATA_HOME:-~/.local/share}/skill-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/skill-homunculus`
+3. `$HOME/.local/share/skill-homunculus`
+
+Existing users with data at `~/.claude/homunculus` can migrate once:
+
+```bash
+bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh
+```
+
+## Quick Start
+
+### 1. Enable Observation Hooks
+
+**If installed as a plugin** (recommended):
+
+No extra `settings.json` hook block is required. Claude Code v2.1+ auto-loads the plugin `hooks/hooks.json`, and `observe.sh` is already registered there.
+
+If you previously copied `observe.sh` into `~/.claude/settings.json`, remove that duplicate `PreToolUse` / `PostToolUse` block. Duplicating the plugin hook causes double execution and `${CLAUDE_PLUGIN_ROOT}` resolution errors because that variable is only available inside plugin-managed `hooks/hooks.json` entries.
+
+**If installed manually** to `~/.claude/skills`, add this to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
+      }]
+    }],
+    "PostToolUse": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
+      }]
+    }]
+  }
+}
+```
+
+### 2. Initialize Directory Structure
+
+The system creates directories automatically on first use, but you can also create them manually:
+
+```bash
+# Global directories
+mkdir -p "${XDG_DATA_HOME:-$HOME/.local/share}/skill-homunculus"/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}
+
+# Project directories are auto-created when the hook first runs in a git repo
+```
+
+### 3. Use the Instinct Commands
+
+```bash
+/instinct-status     # Show learned instincts (project + global)
+/evolve              # Cluster related instincts into skills/commands
+/instinct-export     # Export instincts to file
+/instinct-import     # Import instincts from others
+/promote             # Promote project instincts to global scope
+/projects            # List all known projects and their instinct counts
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/instinct-status` | Show all instincts (project-scoped + global) with confidence |
+| `/evolve` | Cluster related instincts into skills/commands, suggest promotions |
+| `/instinct-export` | Export instincts (filterable by scope/domain) |
+| `/instinct-import <file>` | Import instincts with scope control |
+| `/promote [id]` | Promote project instincts to global scope |
+| `/projects` | List all known projects and their instinct counts |
+
+## Configuration
+
+Edit `config.json` to control the background observer:
+
+```json
+{
+  "version": "2.1",
+  "observer": {
+    "enabled": false,
+    "run_interval_minutes": 5,
+    "min_observations_to_analyze": 20
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `observer.enabled` | `false` | Enable the background observer agent |
+| `observer.run_interval_minutes` | `5` | How often the observer analyzes observations |
+| `observer.min_observations_to_analyze` | `20` | Minimum observations before analysis runs |
+
+Other behavior (observation capture, instinct thresholds, project scoping, promotion criteria) is configured via code defaults in `instinct-cli.py` and `observe.sh`.
+
+## File Structure
+
+```
+${XDG_DATA_HOME:-~/.local/share}/skill-homunculus/
++-- identity.json           # Your profile, technical level
++-- projects.json           # Registry: project hash -> name/path/remote
++-- observations.jsonl      # Global observations (fallback)
++-- instincts/
+|   +-- personal/           # Global auto-learned instincts
+|   +-- inherited/          # Global imported instincts
++-- evolved/
+|   +-- agents/             # Global generated agents
+|   +-- skills/             # Global generated skills
+|   +-- commands/           # Global generated commands
++-- projects/
+    +-- a1b2c3d4e5f6/       # Project hash (from git remote URL)
+    |   +-- project.json    # Per-project metadata mirror (id/name/root/remote)
+    |   +-- observations.jsonl
+    |   +-- observations.archive/
+    |   +-- instincts/
+    |   |   +-- personal/   # Project-specific auto-learned
+    |   |   +-- inherited/  # Project-specific imported
+    |   +-- evolved/
+    |       +-- skills/
+    |       +-- commands/
+    |       +-- agents/
+    +-- f6e5d4c3b2a1/       # Another project
+        +-- ...
+```
+
+## Scope Decision Guide
+
+| Pattern Type | Scope | Examples |
+|-------------|-------|---------|
+| Language/framework conventions | **project** | "Use React hooks", "Follow Django REST patterns" |
+| File structure preferences | **project** | "Tests in `__tests__`/", "Components in src/components/" |
+| Code style | **project** | "Use functional style", "Prefer dataclasses" |
+| Error handling strategies | **project** | "Use Result type for errors" |
+| Security practices | **global** | "Validate user input", "Sanitize SQL" |
+| General best practices | **global** | "Write tests first", "Always handle errors" |
+| Tool workflow preferences | **global** | "Grep before Edit", "Read before Write" |
+| Git practices | **global** | "Conventional commits", "Small focused commits" |
+
+## Instinct Promotion (Project -> Global)
+
+When the same instinct appears in multiple projects with high confidence, it's a candidate for promotion to global scope.
+
+**Auto-promotion criteria:**
+- Same instinct ID in 2+ projects
+- Average confidence >= 0.8
+
+**How to promote:**
+
+```bash
+# Promote a specific instinct
+python3 instinct-cli.py promote prefer-explicit-errors
+
+# Auto-promote all qualifying instincts
+python3 instinct-cli.py promote
+
+# Preview without changes
+python3 instinct-cli.py promote --dry-run
+```
+
+The `/evolve` command also suggests promotion candidates.
+
+## Confidence Scoring
+
+Confidence evolves over time:
+
+| Score | Meaning | Behavior |
+|-------|---------|----------|
+| 0.3 | Tentative | Suggested but not enforced |
+| 0.5 | Moderate | Applied when relevant |
+| 0.7 | Strong | Auto-approved for application |
+| 0.9 | Near-certain | Core behavior |
+
+**Confidence increases** when:
+- Pattern is repeatedly observed
+- User doesn't correct the suggested behavior
+- Similar instincts from other sources agree
+
+**Confidence decreases** when:
+- User explicitly corrects the behavior
+- Pattern isn't observed for extended periods
+- Contradicting evidence appears
+
+## Why Hooks vs Skills for Observation?
+
+> "v1 relied on skills to observe. Skills are probabilistic -- they fire ~50-80% of the time based on Claude's judgment."
+
+Hooks fire **100% of the time**, deterministically. This means:
+- Every tool call is observed
+- No patterns are missed
+- Learning is comprehensive
+
+## Backward Compatibility
+
+v2.1 is fully compatible with v2.0 and v1:
+- 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 parallel
+
+## Privacy
+
+- Observations stay **local** on your machine
+- Project-scoped instincts are isolated per project
+- Only **instincts** (patterns) can be exported — not raw observations
+- No actual code or conversation content is shared
+- You control what gets exported and promoted
+
+## Related
+
+- Homunculus - Community project that inspired the v2 instinct-based architecture (atomic observations, confidence scoring, instinct evolution pipeline)
+
+---
+
+*Instinct-based learning: teaching Claude your patterns, one project at a time.*

package/skills/continuous-learning-v2/agents/observer-loop.sh

@@ -0,0 +1,322 @@
+#!/usr/bin/env bash
+# Continuous Learning v2 - Observer background loop
+#
+# Fix for #521: Added re-entrancy guard, cooldown throttle, and
+# tail-based sampling to prevent memory explosion from runaway
+# parallel Claude analysis processes.
+
+set +e
+unset CLAUDECODE
+
+SLEEP_PID=""
+USR1_FIRED=0
+PENDING_ANALYSIS=0
+ANALYZING=0
+LAST_ANALYSIS_EPOCH=0
+# Minimum seconds between analyses (prevents rapid re-triggering)
+ANALYSIS_COOLDOWN="${SKILLFORGE_OBSERVER_ANALYSIS_COOLDOWN:-60}"
+IDLE_TIMEOUT_SECONDS="${SKILLFORGE_OBSERVER_IDLE_TIMEOUT_SECONDS:-1800}"
+SESSION_LEASE_DIR="${PROJECT_DIR}/.observer-sessions"
+ACTIVITY_FILE="${PROJECT_DIR}/.observer-last-activity"
+
+cleanup() {
+  [ -n "$SLEEP_PID" ] && kill "$SLEEP_PID" 2>/dev/null
+  if [ -f "$PID_FILE" ] && [ "$(cat "$PID_FILE" 2>/dev/null)" = "$$" ]; then
+    rm -f "$PID_FILE"
+  fi
+  exit 0
+}
+trap cleanup TERM INT
+
+file_mtime_epoch() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    printf '0\n'
+    return
+  fi
+
+  if stat -c %Y "$file" >/dev/null 2>&1; then
+    stat -c %Y "$file" 2>/dev/null || printf '0\n'
+    return
+  fi
+
+  if stat -f %m "$file" >/dev/null 2>&1; then
+    stat -f %m "$file" 2>/dev/null || printf '0\n'
+    return
+  fi
+
+  printf '0\n'
+}
+
+has_active_session_leases() {
+  if [ ! -d "$SESSION_LEASE_DIR" ]; then
+    return 1
+  fi
+
+  find "$SESSION_LEASE_DIR" -type f -name '*.json' -print -quit 2>/dev/null | grep -q .
+}
+
+latest_activity_epoch() {
+  local observations_epoch activity_epoch
+  observations_epoch="$(file_mtime_epoch "$OBSERVATIONS_FILE")"
+  activity_epoch="$(file_mtime_epoch "$ACTIVITY_FILE")"
+
+  if [ "$activity_epoch" -gt "$observations_epoch" ] 2>/dev/null; then
+    printf '%s\n' "$activity_epoch"
+  else
+    printf '%s\n' "$observations_epoch"
+  fi
+}
+
+exit_if_idle_without_sessions() {
+  if has_active_session_leases; then
+    return
+  fi
+
+  local last_activity now_epoch idle_for
+  last_activity="$(latest_activity_epoch)"
+  now_epoch="$(date +%s)"
+  idle_for=$(( now_epoch - last_activity ))
+
+  if [ "$last_activity" -eq 0 ] || [ "$idle_for" -ge "$IDLE_TIMEOUT_SECONDS" ]; then
+    echo "[$(date)] Observer idle without active session leases for ${idle_for}s; exiting" >> "$LOG_FILE"
+    cleanup
+  fi
+}
+
+wait_for_claude_analysis() {
+  local child_pid="$1"
+  local wait_status=0
+
+  while true; do
+    wait "$child_pid"
+    wait_status=$?
+
+    if [ "$wait_status" -eq 0 ]; then
+      return 0
+    fi
+
+    # SIGUSR1 can interrupt wait while the Claude child is still running.
+    # Re-wait in that case so a signal is not logged as a false child failure.
+    if kill -0 "$child_pid" 2>/dev/null; then
+      continue
+    fi
+
+    return "$wait_status"
+  done
+}
+
+analyze_observations() {
+  if [ ! -f "$OBSERVATIONS_FILE" ]; then
+    return
+  fi
+
+  obs_count=$(wc -l < "$OBSERVATIONS_FILE" 2>/dev/null || echo 0)
+  if [ "$obs_count" -lt "$MIN_OBSERVATIONS" ]; then
+    return
+  fi
+
+  echo "[$(date)] Analyzing $obs_count observations for project ${PROJECT_NAME}..." >> "$LOG_FILE"
+
+  if [ "${CLV2_IS_WINDOWS:-false}" = "true" ] && [ "${SKILLFORGE_OBSERVER_ALLOW_WINDOWS:-false}" != "true" ]; then
+    echo "[$(date)] Skipping claude analysis on Windows due to known non-interactive hang issue (#295). Set SKILLFORGE_OBSERVER_ALLOW_WINDOWS=true to override." >> "$LOG_FILE"
+    return
+  fi
+
+  if ! command -v claude >/dev/null 2>&1; then
+    echo "[$(date)] claude CLI not found, skipping analysis" >> "$LOG_FILE"
+    return
+  fi
+
+  # session-guardian: gate observer cycle (active hours, cooldown, idle detection)
+  if ! bash "$(dirname "$0")/session-guardian.sh"; then
+    echo "[$(date)] Observer cycle skipped by session-guardian" >> "$LOG_FILE"
+    return
+  fi
+
+  # Sample recent observations instead of loading the entire file (#521).
+  # This prevents multi-MB payloads from being passed to the LLM.
+  MAX_ANALYSIS_LINES="${SKILLFORGE_OBSERVER_MAX_ANALYSIS_LINES:-500}"
+  observer_tmp_dir="${PROJECT_DIR}/.observer-tmp"
+  mkdir -p "$observer_tmp_dir"
+  analysis_file="$(mktemp "${observer_tmp_dir}/sf-observer-analysis.XXXXXX.jsonl")"
+  tail -n "$MAX_ANALYSIS_LINES" "$OBSERVATIONS_FILE" > "$analysis_file"
+  analysis_count=$(wc -l < "$analysis_file" 2>/dev/null || echo 0)
+  echo "[$(date)] Using last $analysis_count of $obs_count observations for analysis" >> "$LOG_FILE"
+
+  # Use relative path from PROJECT_DIR for cross-platform compatibility (#842).
+  # On Windows (Git Bash/MSYS2), absolute paths from mktemp may use MSYS-style
+  # prefixes (e.g. /c/Users/...) that the Claude subprocess cannot resolve.
+  analysis_relpath=".observer-tmp/$(basename "$analysis_file")"
+
+  prompt_file="$(mktemp "${observer_tmp_dir}/sf-observer-prompt.XXXXXX")"
+  cat > "$prompt_file" <<PROMPT
+IMPORTANT: You are running in non-interactive --print mode. You MUST use the Write tool directly to create files. Do NOT ask for permission, do NOT ask for confirmation, do NOT output summaries instead of writing. Just read, analyze, and write.
+
+Read ${analysis_relpath} and identify patterns for the project ${PROJECT_NAME} (user corrections, error resolutions, repeated workflows, tool preferences).
+If you find 3+ occurrences of the same pattern, you MUST write an instinct file directly to ${INSTINCTS_DIR}/<id>.md using the Write tool.
+Do NOT ask for permission to write files, do NOT describe what you would write, and do NOT stop at analysis when a qualifying pattern exists.
+
+CRITICAL: Every instinct file MUST use this exact format:
+
+---
+id: kebab-case-name
+trigger: when <specific condition>
+confidence: <0.3-0.85 based on frequency: 3-5 times=0.5, 6-10=0.7, 11+=0.85>
+domain: <one of: code-style, testing, git, debugging, workflow, file-patterns>
+source: session-observation
+scope: project
+project_id: ${PROJECT_ID}
+project_name: ${PROJECT_NAME}
+---
+
+# Title
+
+## Action
+<what to do, one clear sentence>
+
+## Evidence
+- Observed N times in session <id>
+- Pattern: <description>
+- Last observed: <date>
+
+Rules:
+- Be conservative, only clear patterns with 3+ observations
+- Use narrow, specific triggers
+- Never include actual code snippets, only describe patterns
+- When a qualifying pattern exists, write or update the instinct file in this run instead of asking for confirmation
+- If a similar instinct already exists in ${INSTINCTS_DIR}/, update it instead of creating a duplicate
+- The YAML frontmatter (between --- markers) with id field is MANDATORY
+- If a pattern seems universal (not project-specific), set scope to global instead of project
+- Examples of global patterns: always validate user input, prefer explicit error handling
+- Examples of project patterns: use React functional components, follow Django REST framework conventions
+PROMPT
+
+  # Read the prompt into memory before the Claude subprocess is spawned.
+  # On Windows/MSYS2, the mktemp path can differ from the shell's later path
+  # resolution, so relying on cat "$prompt_file" inside the claude invocation
+  # can fail even though the file was created successfully.
+  prompt_content="$(cat "$prompt_file" 2>/dev/null || true)"
+  rm -f "$prompt_file"
+  if [ -z "$prompt_content" ]; then
+    echo "[$(date)] Failed to load observer prompt content, skipping analysis" >> "$LOG_FILE"
+    rm -f "$analysis_file"
+    return
+  fi
+
+  timeout_seconds="${SKILLFORGE_OBSERVER_TIMEOUT_SECONDS:-120}"
+  max_turns="${SKILLFORGE_OBSERVER_MAX_TURNS:-20}"
+  exit_code=0
+
+  case "$max_turns" in
+    ''|*[!0-9]*)
+      max_turns=20
+      ;;
+  esac
+
+  if [ "$max_turns" -lt 4 ]; then
+    max_turns=20
+  fi
+
+  # Ensure CWD is PROJECT_DIR so the relative analysis_relpath resolves correctly
+  # on all platforms, not just when the observer happens to be launched from the project root.
+  cd "$PROJECT_DIR" || { echo "[$(date)] Failed to cd to PROJECT_DIR ($PROJECT_DIR), skipping analysis" >> "$LOG_FILE"; rm -f "$analysis_file"; return; }
+
+  # Prevent observe.sh from recording this automated Haiku session as observations.
+  # Pass prompt via -p flag instead of stdin redirect for Windows compatibility (#842).
+  # prompt_content is already loaded in-memory so this no longer depends on the
+  # mktemp absolute path continuing to resolve after cwd changes (#1296).
+  SKILLFORGE_SKIP_OBSERVE=1 SKILLFORGE_HOOK_PROFILE=minimal claude --model haiku --max-turns "$max_turns" --print \
+    --allowedTools "Read,Write" \
+    -p "$prompt_content" >> "$LOG_FILE" 2>&1 &
+  claude_pid=$!
+
+  (
+    sleep "$timeout_seconds"
+    if kill -0 "$claude_pid" 2>/dev/null; then
+      echo "[$(date)] Claude analysis timed out after ${timeout_seconds}s; terminating process" >> "$LOG_FILE"
+      kill "$claude_pid" 2>/dev/null || true
+    fi
+  ) &
+  watchdog_pid=$!
+
+  wait_for_claude_analysis "$claude_pid"
+  exit_code=$?
+  kill "$watchdog_pid" 2>/dev/null || true
+  rm -f "$analysis_file"
+
+  if [ "$exit_code" -ne 0 ]; then
+    echo "[$(date)] Claude analysis failed (exit $exit_code)" >> "$LOG_FILE"
+  fi
+
+  if [ -f "$OBSERVATIONS_FILE" ]; then
+    archive_dir="${PROJECT_DIR}/observations.archive"
+    mkdir -p "$archive_dir"
+    mv "$OBSERVATIONS_FILE" "$archive_dir/processed-$(date +%Y%m%d-%H%M%S)-$$.jsonl" 2>/dev/null || true
+  fi
+}
+
+on_usr1() {
+  [ -n "$SLEEP_PID" ] && kill "$SLEEP_PID" 2>/dev/null
+  SLEEP_PID=""
+
+  # 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
+    PENDING_ANALYSIS=1
+    echo "[$(date)] Analysis already in progress, deferring signal" >> "$LOG_FILE"
+    return
+  fi
+
+  USR1_FIRED=1
+
+  # Cooldown: skip if last analysis was too recent (#521)
+  now_epoch=$(date +%s)
+  elapsed=$(( now_epoch - LAST_ANALYSIS_EPOCH ))
+  if [ "$elapsed" -lt "$ANALYSIS_COOLDOWN" ]; then
+    echo "[$(date)] Analysis cooldown active (${elapsed}s < ${ANALYSIS_COOLDOWN}s), skipping" >> "$LOG_FILE"
+    return
+  fi
+
+  ANALYZING=1
+  analyze_observations
+  LAST_ANALYSIS_EPOCH=$(date +%s)
+  ANALYZING=0
+}
+trap on_usr1 USR1
+
+echo "$$" > "$PID_FILE"
+echo "[$(date)] Observer started for ${PROJECT_NAME} (PID: $$)" >> "$LOG_FILE"
+
+# Prune expired pending instincts before analysis
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+"${CLV2_PYTHON_CMD:-python3}" "${SCRIPT_DIR}/../scripts/instinct-cli.py" prune --quiet >> "$LOG_FILE" 2>&1 || echo "[$(date)] Warning: instinct prune failed (non-fatal)" >> "$LOG_FILE"
+
+while true; do
+  exit_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
+  SLEEP_PID=""
+
+  exit_if_idle_without_sessions
+  if [ "$USR1_FIRED" -eq 1 ]; then
+    USR1_FIRED=0
+  else
+    ANALYZING=1
+    analyze_observations
+    LAST_ANALYSIS_EPOCH=$(date +%s)
+    ANALYZING=0
+  fi
+done