feat: project-scoped instinct isolation

* feat: add project-scoped instinct isolation * fix(continuous-learning-v2): harden instinct loading and promotion safety; sync v2.1 command docs * fix(ci): make copilot-setup-steps a valid GitHub Actions workflow * fix(hooks): stabilize docs warning inline JS regex parsing
2026-04-10 11:23:32 +08:00 · 2026-03-02 04:07:13 +08:00
parent 2d3be88bb5
commit 5818e8adc7
26 changed files with 2476 additions and 713 deletions
--- a/skills/continuous-learning-v2/agents/observer.md
+++ b/skills/continuous-learning-v2/agents/observer.md
@@ -1,8 +1,7 @@
 ---
 name: observer
-description: Background agent that analyzes session observations to detect patterns and create instincts. Uses Haiku for cost-efficiency.
+description: Background agent that analyzes session observations to detect patterns and create instincts. Uses Haiku for cost-efficiency. v2.1 adds project-scoped instincts.
 model: haiku
-run_mode: background
 ---

 # Observer Agent
@@ -11,20 +10,21 @@ A background agent that analyzes observations from Claude Code sessions to detec

 ## When to Run

- After significant session activity (20+ tool calls)
- When user runs `/analyze-patterns`
+- After enough observations accumulate (configurable, default 20)
 - On a scheduled interval (configurable, default 5 minutes)
- When triggered by observation hook (SIGUSR1)
+- When triggered on demand via SIGUSR1 to the observer process

 ## Input

-Reads observations from `~/.claude/homunculus/observations.jsonl`:
+Reads observations from the **project-scoped** observations file:
+- Project: `~/.claude/homunculus/projects/<project-hash>/observations.jsonl`
+- Global fallback: `~/.claude/homunculus/observations.jsonl`

 ```jsonl
-{"timestamp":"2025-01-22T10:30:00Z","event":"tool_start","session":"abc123","tool":"Edit","input":"..."}
-{"timestamp":"2025-01-22T10:30:01Z","event":"tool_complete","session":"abc123","tool":"Edit","output":"..."}
-{"timestamp":"2025-01-22T10:30:05Z","event":"tool_start","session":"abc123","tool":"Bash","input":"npm test"}
-{"timestamp":"2025-01-22T10:30:10Z","event":"tool_complete","session":"abc123","tool":"Bash","output":"All tests pass"}
+{"timestamp":"2025-01-22T10:30:00Z","event":"tool_start","session":"abc123","tool":"Edit","input":"...","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
+{"timestamp":"2025-01-22T10:30:01Z","event":"tool_complete","session":"abc123","tool":"Edit","output":"...","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
+{"timestamp":"2025-01-22T10:30:05Z","event":"tool_start","session":"abc123","tool":"Bash","input":"npm test","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
+{"timestamp":"2025-01-22T10:30:10Z","event":"tool_complete","session":"abc123","tool":"Bash","output":"All tests pass","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
 ```

 ## Pattern Detection
@@ -65,28 +65,75 @@ When certain tools are consistently preferred:

 ## Output

-Creates/updates instincts in `~/.claude/homunculus/instincts/personal/`:
+Creates/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-Scoped Instinct (default)

 ```yaml
 ---
-id: prefer-grep-before-edit
-trigger: "when searching for code to modify"
+id: use-react-hooks-pattern
+trigger: "when creating React components"
 confidence: 0.65
-domain: "workflow"
+domain: "code-style"
 source: "session-observation"
+scope: project
+project_id: "a1b2c3d4e5f6"
+project_name: "my-react-app"
 ---

-# Prefer Grep Before Edit
+# Use React Hooks Pattern

 ## Action
-Always use Grep to find the exact location before using Edit.
+Always use functional components with hooks instead of class components.

 ## Evidence
 - Observed 8 times in session abc123
- Pattern: Grep → Read → Edit sequence
+- Pattern: All new components use useState/useEffect
 - Last observed: 2025-01-22
 ```

+### Global Instinct (universal patterns)
+
+```yaml
+---
+id: always-validate-user-input
+trigger: "when handling user input"
+confidence: 0.75
+domain: "security"
+source: "session-observation"
+scope: global
+---
+
+# Always Validate User Input
+
+## Action
+Validate and sanitize all user input before processing.
+
+## Evidence
+- Observed across 3 different projects
+- Pattern: User consistently adds input validation
+- Last observed: 2025-01-22
+```
+
+## Scope Decision Guide
+
+When creating instincts, determine scope based on these heuristics:
+
+| 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** (usually) | "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" |
+
+**When in doubt, default to `scope: project`** — it's safer to be project-specific and promote later than to contaminate the global space.
+
 ## Confidence Calculation

 Initial confidence based on observation frequency:
@@ -100,6 +147,15 @@ Confidence adjusts over time:
 - -0.1 for each contradicting observation
 - -0.02 per week without observation (decay)

+## Instinct Promotion (Project → Global)
+
+An instinct should be promoted from project-scoped to global when:
+1. The **same pattern** (by id or similar trigger) exists in **2+ different projects**
+2. Each instance has confidence **>= 0.8**
+3. The domain is in the global-friendly list (security, general-best-practices, workflow)
+
+Promotion is handled by the `instinct-cli.py promote` command or the `/evolve` analysis.
+
 ## Important Guidelines

 1. **Be Conservative**: Only create instincts for clear patterns (3+ observations)
@@ -107,31 +163,36 @@ Confidence adjusts over time:
 3. **Track Evidence**: Always include what observations led to the instinct
 4. **Respect Privacy**: Never include actual code snippets, only patterns
 5. **Merge Similar**: If a new instinct is similar to existing, update rather than duplicate
+6. **Default to Project Scope**: Unless the pattern is clearly universal, make it project-scoped
+7. **Include Project Context**: Always set `project_id` and `project_name` for project-scoped instincts

 ## Example Analysis Session

 Given observations:
 ```jsonl
-{"event":"tool_start","tool":"Grep","input":"pattern: useState"}
-{"event":"tool_complete","tool":"Grep","output":"Found in 3 files"}
-{"event":"tool_start","tool":"Read","input":"src/hooks/useAuth.ts"}
-{"event":"tool_complete","tool":"Read","output":"[file content]"}
-{"event":"tool_start","tool":"Edit","input":"src/hooks/useAuth.ts..."}
+{"event":"tool_start","tool":"Grep","input":"pattern: useState","project_id":"a1b2c3","project_name":"my-app"}
+{"event":"tool_complete","tool":"Grep","output":"Found in 3 files","project_id":"a1b2c3","project_name":"my-app"}
+{"event":"tool_start","tool":"Read","input":"src/hooks/useAuth.ts","project_id":"a1b2c3","project_name":"my-app"}
+{"event":"tool_complete","tool":"Read","output":"[file content]","project_id":"a1b2c3","project_name":"my-app"}
+{"event":"tool_start","tool":"Edit","input":"src/hooks/useAuth.ts...","project_id":"a1b2c3","project_name":"my-app"}
 ```

 Analysis:
 - Detected workflow: Grep → Read → Edit
 - Frequency: Seen 5 times this session
+- **Scope decision**: This is a general workflow pattern (not project-specific) → **global**
 - Create instinct:
  - trigger: "when modifying code"
  - action: "Search with Grep, confirm with Read, then Edit"
  - confidence: 0.6
  - domain: "workflow"
+  - scope: "global"

 ## Integration with Skill Creator

 When instincts are imported from Skill Creator (repo analysis), they have:
 - `source: "repo-analysis"`
 - `source_repo: "https://github.com/..."`
+- `scope: "project"` (since they come from a specific repo)

 These should be treated as team/project conventions with higher initial confidence (0.7+).
--- a/skills/continuous-learning-v2/agents/start-observer.sh
+++ b/skills/continuous-learning-v2/agents/start-observer.sh
@@ -4,26 +4,79 @@
 # Starts the background observer agent that analyzes observations
 # and creates instincts. Uses Haiku model for cost efficiency.
 #
+# v2.1: Project-scoped — detects current project and analyzes
+#       project-specific observations into project-scoped instincts.
+#
 # Usage:
-#   start-observer.sh        # Start observer in background
+#   start-observer.sh        # Start observer for current project (or global)
 #   start-observer.sh stop   # Stop running observer
 #   start-observer.sh status # Check if observer is running

 set -e

-CONFIG_DIR="${HOME}/.claude/homunculus"
-PID_FILE="${CONFIG_DIR}/.observer.pid"
-LOG_FILE="${CONFIG_DIR}/observer.log"
-OBSERVATIONS_FILE="${CONFIG_DIR}/observations.jsonl"
+# ─────────────────────────────────────────────
+# Project detection
+# ─────────────────────────────────────────────

-mkdir -p "$CONFIG_DIR"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Source shared project detection helper
+# This sets: PROJECT_ID, PROJECT_NAME, PROJECT_ROOT, PROJECT_DIR
+source "${SKILL_ROOT}/scripts/detect-project.sh"
+
+# ─────────────────────────────────────────────
+# Configuration
+# ─────────────────────────────────────────────
+
+CONFIG_DIR="${HOME}/.claude/homunculus"
+CONFIG_FILE="${SKILL_ROOT}/config.json"
+# PID file is project-scoped so each project can have its own observer
+PID_FILE="${PROJECT_DIR}/.observer.pid"
+LOG_FILE="${PROJECT_DIR}/observer.log"
+OBSERVATIONS_FILE="${PROJECT_DIR}/observations.jsonl"
+INSTINCTS_DIR="${PROJECT_DIR}/instincts/personal"
+
+# Read config values from config.json
+OBSERVER_INTERVAL_MINUTES=5
+MIN_OBSERVATIONS=20
+OBSERVER_ENABLED=false
+if [ -f "$CONFIG_FILE" ]; then
+  _config=$(CLV2_CONFIG="$CONFIG_FILE" python3 -c "
+import json, os
+with open(os.environ['CLV2_CONFIG']) as f:
+    cfg = json.load(f)
+obs = cfg.get('observer', {})
+print(obs.get('run_interval_minutes', 5))
+print(obs.get('min_observations_to_analyze', 20))
+print(str(obs.get('enabled', False)).lower())
+" 2>/dev/null || echo "5
+20
+false")
+  _interval=$(echo "$_config" | sed -n '1p')
+  _min_obs=$(echo "$_config" | sed -n '2p')
+  _enabled=$(echo "$_config" | sed -n '3p')
+  if [ "$_interval" -gt 0 ] 2>/dev/null; then
+    OBSERVER_INTERVAL_MINUTES="$_interval"
+  fi
+  if [ "$_min_obs" -gt 0 ] 2>/dev/null; then
+    MIN_OBSERVATIONS="$_min_obs"
+  fi
+  if [ "$_enabled" = "true" ]; then
+    OBSERVER_ENABLED=true
+  fi
+fi
+OBSERVER_INTERVAL_SECONDS=$((OBSERVER_INTERVAL_MINUTES * 60))
+
+echo "Project: ${PROJECT_NAME} (${PROJECT_ID})"
+echo "Storage: ${PROJECT_DIR}"

 case "${1:-start}" in
  stop)
    if [ -f "$PID_FILE" ]; then
      pid=$(cat "$PID_FILE")
      if kill -0 "$pid" 2>/dev/null; then
-        echo "Stopping observer (PID: $pid)..."
+        echo "Stopping observer for ${PROJECT_NAME} (PID: $pid)..."
        kill "$pid"
        rm -f "$PID_FILE"
        echo "Observer stopped."
@@ -44,6 +97,9 @@ case "${1:-start}" in
        echo "Observer is running (PID: $pid)"
        echo "Log: $LOG_FILE"
        echo "Observations: $(wc -l < "$OBSERVATIONS_FILE" 2>/dev/null || echo 0) lines"
+        # Also show instinct count
+        instinct_count=$(find "$INSTINCTS_DIR" -name "*.yaml" 2>/dev/null | wc -l)
+        echo "Instincts: $instinct_count"
        exit 0
      else
        echo "Observer not running (stale PID file)"
@@ -57,17 +113,24 @@ case "${1:-start}" in
    ;;

  start)
+    # Check if observer is disabled in config
+    if [ "$OBSERVER_ENABLED" != "true" ]; then
+      echo "Observer is disabled in config.json (observer.enabled: false)."
+      echo "Set observer.enabled to true in config.json to enable."
+      exit 1
+    fi
+
    # Check if already running
    if [ -f "$PID_FILE" ]; then
      pid=$(cat "$PID_FILE")
      if kill -0 "$pid" 2>/dev/null; then
-        echo "Observer already running (PID: $pid)"
+        echo "Observer already running for ${PROJECT_NAME} (PID: $pid)"
        exit 0
      fi
      rm -f "$PID_FILE"
    fi

-    echo "Starting observer agent..."
+    echo "Starting observer agent for ${PROJECT_NAME}..."

    # The observer loop
    (
@@ -79,18 +142,43 @@ case "${1:-start}" in
          return
        fi
        obs_count=$(wc -l < "$OBSERVATIONS_FILE" 2>/dev/null || echo 0)
-        if [ "$obs_count" -lt 10 ]; then
+        if [ "$obs_count" -lt "$MIN_OBSERVATIONS" ]; then
          return
        fi

-        echo "[$(date)] Analyzing $obs_count observations..." >> "$LOG_FILE"
+        echo "[$(date)] Analyzing $obs_count observations for project ${PROJECT_NAME}..." >> "$LOG_FILE"

        # Use Claude Code with Haiku to analyze observations
-        # This spawns a quick analysis session
+        # The prompt now specifies project-scoped instinct creation
        if command -v claude &> /dev/null; then
          exit_code=0
-          claude --model haiku --max-turns 3 --print \
-            "Read $OBSERVATIONS_FILE and identify patterns. If you find 3+ occurrences of the same pattern, create an instinct file in $CONFIG_DIR/instincts/personal/ following the format in the observer agent spec. Be conservative - only create instincts for clear patterns." \
+          claude --model haiku --print \
+            "Read $OBSERVATIONS_FILE and identify patterns for the project '${PROJECT_NAME}'.
+If you find 3+ occurrences of the same pattern, create an instinct file in $INSTINCTS_DIR/ following this format:
+
+---
+id: <kebab-case-id>
+trigger: \"<when this happens>\"
+confidence: <0.3-0.9>
+domain: <code-style|testing|git|debugging|workflow|etc>
+source: session-observation
+scope: project
+project_id: ${PROJECT_ID}
+project_name: ${PROJECT_NAME}
+---
+
+# <Title>
+
+## Action
+<What to do>
+
+## Evidence
+<What observations led to this>
+
+Be conservative - only create instincts for clear patterns.
+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'." \
            >> "$LOG_FILE" 2>&1 || exit_code=$?
          if [ "$exit_code" -ne 0 ]; then
            echo "[$(date)] Claude analysis failed (exit $exit_code)" >> "$LOG_FILE"
@@ -101,10 +189,9 @@ case "${1:-start}" in

        # Archive processed observations
        if [ -f "$OBSERVATIONS_FILE" ]; then
-          archive_dir="${CONFIG_DIR}/observations.archive"
+          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
-          touch "$OBSERVATIONS_FILE"
+          mv "$OBSERVATIONS_FILE" "$archive_dir/processed-$(date +%Y%m%d-%H%M%S)-$$.jsonl" 2>/dev/null || true
        fi
      }

@@ -112,11 +199,11 @@ case "${1:-start}" in
      trap 'analyze_observations' USR1

      echo "$$" > "$PID_FILE"
-      echo "[$(date)] Observer started (PID: $$)" >> "$LOG_FILE"
+      echo "[$(date)] Observer started for ${PROJECT_NAME} (PID: $$)" >> "$LOG_FILE"

      while true; do
-        # Check every 5 minutes
-        sleep 300
+        # Check at configured interval (default: 5 minutes)
+        sleep "$OBSERVER_INTERVAL_SECONDS"

        analyze_observations
      done