Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat: project-scoped instinct isolation

Harry Kwok5818e8adc71e
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
index f9593bbf5..a9b9ccb2b 100644
--- a/.github/workflows/copilot-setup-steps.yml
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -1,18 +1,30 @@
-steps:
- - name: Setup Go environment
- uses: actions/[email protected]
- with:
- # The Go version to download (if necessary) and use. Supports semver spec and ranges. Be sure to enclose this option in single quotation marks.
- go-version: # optional
- # Path to the go.mod, go.work, .go-version, or .tool-versions file.
- go-version-file: # optional
- # Set this option to true if you want the action to always check for the latest available version that satisfies the version spec
- check-latest: # optional
- # Used to pull Go distributions from go-versions. Since there's a default, this is typically not supplied by the user. When running this action on github.com, the default value is sufficient. When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting.
- token: # optional, default is ${{ github.server_url == 'https://github.com' && github.token || '' }}
- # Used to specify whether caching is needed. Set to true, if you'd like to enable caching.
- cache: # optional, default is true
- # Used to specify the path to a dependency file - go.sum
- cache-dependency-path: # optional
- # Target architecture for Go to use. Examples: x86, x64. Will use system architecture by default.
- architecture: # optional
+name: Copilot Setup Steps
+
+on:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ copilot-setup-steps:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: "20"
+ cache: npm
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Verify environment
+ run: |
+ node --version
+ npm --version
+ python3 --version
diff --git a/.opencode/MIGRATION.md b/.opencode/MIGRATION.md
index 914b0e2f6..2277d7aea 100644
--- a/.opencode/MIGRATION.md
+++ b/.opencode/MIGRATION.md
@@ -258,6 +258,8 @@ After migration, ALL 23 commands are available:
| `/instinct-import` | Import instincts |
| `/instinct-export` | Export instincts |
| `/evolve` | Cluster instincts into skills |
+| `/promote` | Promote project instincts to global scope |
+| `/projects` | List known projects and instinct stats |
## Available Agents
diff --git a/.opencode/README.md b/.opencode/README.md
index 6ee8e2726..2c20e781b 100644
--- a/.opencode/README.md
+++ b/.opencode/README.md
@@ -95,6 +95,8 @@ opencode
| `/instinct-import` | Import instincts |
| `/instinct-export` | Export instincts |
| `/evolve` | Cluster instincts |
+| `/promote` | Promote project instincts |
+| `/projects` | List known projects |
### Plugin Hooks
diff --git a/.opencode/commands/evolve.md b/.opencode/commands/evolve.md
index 5c4c75a1b..6f344a530 100644
--- a/.opencode/commands/evolve.md
+++ b/.opencode/commands/evolve.md
@@ -1,112 +1,36 @@
---
-description: Cluster instincts into skills
+description: Analyze instincts and suggest or generate evolved structures
agent: build
---
# Evolve Command
-Cluster related instincts into structured skills: $ARGUMENTS
+Analyze and evolve instincts in continuous-learning-v2: $ARGUMENTS
## Your Task
-Analyze instincts and promote clusters to skills.
+Run:
-## Evolution Process
-
-### Step 1: Analyze Instincts
-
-Group instincts by:
-- Trigger similarity
-- Action patterns
-- Category tags
-- Confidence levels
-
-### Step 2: Identify Clusters
-
-```
-Cluster: Error Handling
-├── Instinct: Catch specific errors (0.85)
-├── Instinct: Wrap errors with context (0.82)
-├── Instinct: Log errors with stack trace (0.78)
-└── Instinct: Return meaningful error messages (0.80)
-```
-
-### Step 3: Generate Skill
-
-When cluster has:
-- 3+ instincts
-- Average confidence > 0.75
-- Cohesive theme
-
-Generate SKILL.md:
-
-```markdown
-# Error Handling Skill
-
-## Overview
-Patterns for robust error handling learned from session observations.
-
-## Patterns
-
-### 1. Catch Specific Errors
-**Trigger**: When catching errors with generic catch
-**Action**: Use specific error types
-
-### 2. Wrap Errors with Context
-**Trigger**: When re-throwing errors
-**Action**: Add context with fmt.Errorf or Error.cause
-
-### 3. Log with Stack Trace
-**Trigger**: When logging errors
-**Action**: Include stack trace for debugging
-
-### 4. Meaningful Messages
-**Trigger**: When returning errors to users
-**Action**: Provide actionable error messages
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" evolve $ARGUMENTS
```
-### Step 4: Archive Instincts
-
-Move evolved instincts to `archived/` with reference to skill.
-
-## Evolution Report
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve $ARGUMENTS
```
-Evolution Summary
-=================
-
-Clusters Found: X
-
-Cluster 1: Error Handling
-- Instincts: 5
-- Avg Confidence: 0.82
-- Status: ✅ Promoted to skill
-Cluster 2: Testing Patterns
-- Instincts: 3
-- Avg Confidence: 0.71
-- Status: ⏳ Needs more confidence
+## Supported Args (v2.1)
-Cluster 3: Git Workflow
-- Instincts: 2
-- Avg Confidence: 0.88
-- Status: ⏳ Needs more instincts
+- no args: analysis only
+- `--generate`: also generate files under `evolved/{skills,commands,agents}`
-Skills Created:
-- skills/error-handling/SKILL.md
-
-Instincts Archived: 5
-Remaining Instincts: 12
-```
-
-## Thresholds
-
-| Metric | Threshold |
-|--------|-----------|
-| Min instincts per cluster | 3 |
-| Min average confidence | 0.75 |
-| Min cluster cohesion | 0.6 |
-
----
+## Behavior Notes
-**TIP**: Run `/evolve` periodically to graduate instincts to skills as confidence grows.
+- Uses project + global instincts for analysis.
+- Shows skill/command/agent candidates from trigger and domain clustering.
+- Shows project -> global promotion candidates.
+- With `--generate`, output path is:
+ - project context: `~/.claude/homunculus/projects/<project-id>/evolved/`
+ - global fallback: `~/.claude/homunculus/evolved/`
diff --git a/.opencode/commands/instinct-status.md b/.opencode/commands/instinct-status.md
index 7890c4137..5ca7ce8a4 100644
--- a/.opencode/commands/instinct-status.md
+++ b/.opencode/commands/instinct-status.md
@@ -1,75 +1,29 @@
---
-description: View learned instincts with confidence scores
+description: Show learned instincts (project + global) with confidence
agent: build
---
# Instinct Status Command
-Display learned instincts and their confidence scores: $ARGUMENTS
+Show instinct status from continuous-learning-v2: $ARGUMENTS
## Your Task
-Read and display instincts from the continuous-learning-v2 system.
+Run:
-## Instinct Location
-
-Global: `~/.claude/instincts/`
-Project: `.claude/instincts/`
-
-## Status Display
-
-### Instinct Summary
-
-| Category | Count | Avg Confidence |
-|----------|-------|----------------|
-| Coding | X | 0.XX |
-| Testing | X | 0.XX |
-| Security | X | 0.XX |
-| Git | X | 0.XX |
-
-### High Confidence Instincts (>0.8)
-
-```
-[trigger] → [action] (confidence: 0.XX)
-```
-
-### Learning Progress
-
-- Total instincts: X
-- This session: X
-- Promoted to skills: X
-
-### Recent Instincts
-
-Last 5 instincts learned:
-
-1. **[timestamp]** - [trigger] → [action]
-2. **[timestamp]** - [trigger] → [action]
-...
-
-## Instinct Structure
-
-```json
-{
- "id": "instinct-123",
- "trigger": "When I see a try-catch without specific error type",
- "action": "Suggest using specific error types for better handling",
- "confidence": 0.75,
- "applications": 5,
- "successes": 4,
- "source": "session-observation",
- "timestamp": "2025-01-15T10:30:00Z"
-}
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" status
```
-## Confidence Calculation
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
-```
-confidence = (successes + 1) / (applications + 2)
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
```
-Bayesian smoothing ensures new instincts don't have extreme confidence.
-
----
+## Behavior Notes
-**TIP**: Use `/evolve` to cluster related instincts into skills when confidence is high.
+- Output includes both project-scoped and global instincts.
+- Project instincts override global instincts when IDs conflict.
+- Output is grouped by domain with confidence bars.
+- This command does not support extra filters in v2.1.
diff --git a/.opencode/commands/projects.md b/.opencode/commands/projects.md
new file mode 100644
index 000000000..77785d01d
--- /dev/null
+++ b/.opencode/commands/projects.md
@@ -0,0 +1,23 @@
+---
+description: List registered projects and instinct counts
+agent: build
+---
+
+# Projects Command
+
+Show continuous-learning-v2 project registry and stats: $ARGUMENTS
+
+## Your Task
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" projects
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py projects
+```
+
diff --git a/.opencode/commands/promote.md b/.opencode/commands/promote.md
new file mode 100644
index 000000000..566a662e3
--- /dev/null
+++ b/.opencode/commands/promote.md
@@ -0,0 +1,23 @@
+---
+description: Promote project instincts to global scope
+agent: build
+---
+
+# Promote Command
+
+Promote instincts in continuous-learning-v2: $ARGUMENTS
+
+## Your Task
+
+Run:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" promote $ARGUMENTS
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unavailable, use:
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py promote $ARGUMENTS
+```
+
diff --git a/.opencode/opencode.json b/.opencode/opencode.json
index 97a6d1205..476aadce9 100644
--- a/.opencode/opencode.json
+++ b/.opencode/opencode.json
@@ -303,6 +303,14 @@
"evolve": {
"description": "Cluster instincts into skills",
"template": "{file:.opencode/commands/evolve.md}\n\n$ARGUMENTS"
+ },
+ "promote": {
+ "description": "Promote project instincts to global scope",
+ "template": "{file:.opencode/commands/promote.md}\n\n$ARGUMENTS"
+ },
+ "projects": {
+ "description": "List known projects and instinct stats",
+ "template": "{file:.opencode/commands/projects.md}\n\n$ARGUMENTS"
}
},
"permission": {
diff --git a/README.md b/README.md
index 42cc7f7a4..935d8dd20 100644
--- a/README.md
+++ b/README.md
@@ -985,6 +985,8 @@ OpenCode's plugin system is MORE sophisticated than Claude Code with 20+ event t
| `/instinct-import` | Import instincts |
| `/instinct-export` | Export instincts |
| `/evolve` | Cluster instincts into skills |
+| `/promote` | Promote project instincts to global scope |
+| `/projects` | List known projects and instinct stats |
| `/learn-eval` | Extract and evaluate patterns before saving |
| `/setup-pm` | Configure package manager |
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 0952df8e8..ef72d195e 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -287,6 +287,8 @@ everything-claude-code/
/instinct-import <file> # 从他人导入直觉
/instinct-export # 导出你的直觉以供分享
/evolve # 将相关直觉聚类到技能中
+/promote # 将项目级直觉提升为全局直觉
+/projects # 查看已识别项目与直觉统计
```
完整文档见 `skills/continuous-learning-v2/`。
diff --git a/commands/evolve.md b/commands/evolve.md
index 8d4b96c4a..467458e76 100644
--- a/commands/evolve.md
+++ b/commands/evolve.md
@@ -1,6 +1,6 @@
---
name: evolve
-description: Cluster related instincts into skills, commands, or agents
+description: Analyze instincts and suggest or generate evolved structures
command: true
---
@@ -29,9 +29,7 @@ Analyzes instincts and clusters related ones into higher-level structures:
```
/evolve # Analyze all instincts and suggest evolutions
-/evolve --domain testing # Only evolve instincts in testing domain
-/evolve --dry-run # Show what would be created without creating
-/evolve --threshold 5 # Require 5+ related instincts to cluster
+/evolve --generate # Also generate files under evolved/{skills,commands,agents}
```
## Evolution Rules
@@ -78,63 +76,50 @@ Example:
## What to Do
-1. Read all instincts from `~/.claude/homunculus/instincts/`
-2. Group instincts by:
- - Domain similarity
- - Trigger pattern overlap
- - Action sequence relationship
-3. For each cluster of 3+ related instincts:
- - Determine evolution type (command/skill/agent)
- - Generate the appropriate file
- - Save to `~/.claude/homunculus/evolved/{commands,skills,agents}/`
-4. Link evolved structure back to source instincts
+1. Detect current project context
+2. Read project + global instincts (project takes precedence on ID conflicts)
+3. Group instincts by trigger/domain patterns
+4. Identify:
+ - Skill candidates (trigger clusters with 2+ instincts)
+ - Command candidates (high-confidence workflow instincts)
+ - Agent candidates (larger, high-confidence clusters)
+5. Show promotion candidates (project -> global) when applicable
+6. If `--generate` is passed, write files to:
+ - Project scope: `~/.claude/homunculus/projects/<project-id>/evolved/`
+ - Global fallback: `~/.claude/homunculus/evolved/`
## Output Format
```
-🧬 Evolve Analysis
-==================
-
-Found 3 clusters ready for evolution:
-
-## Cluster 1: Database Migration Workflow
-Instincts: new-table-migration, update-schema, regenerate-types
-Type: Command
-Confidence: 85% (based on 12 observations)
-
-Would create: /new-table command
-Files:
- - ~/.claude/homunculus/evolved/commands/new-table.md
-
-## Cluster 2: Functional Code Style
-Instincts: prefer-functional, use-immutable, avoid-classes, pure-functions
-Type: Skill
-Confidence: 78% (based on 8 observations)
-
-Would create: functional-patterns skill
-Files:
- - ~/.claude/homunculus/evolved/skills/functional-patterns.md
-
-## Cluster 3: Debugging Process
-Instincts: debug-check-logs, debug-isolate, debug-reproduce, debug-verify
-Type: Agent
-Confidence: 72% (based on 6 observations)
-
-Would create: debugger agent
-Files:
- - ~/.claude/homunculus/evolved/agents/debugger.md
-
----
-Run `/evolve --execute` to create these files.
+============================================================
+ EVOLVE ANALYSIS - 12 instincts
+ Project: my-app (a1b2c3d4e5f6)
+ Project-scoped: 8 | Global: 4
+============================================================
+
+High confidence instincts (>=80%): 5
+
+## SKILL CANDIDATES
+1. Cluster: "adding tests"
+ Instincts: 3
+ Avg confidence: 82%
+ Domains: testing
+ Scopes: project
+
+## COMMAND CANDIDATES (2)
+ /adding-tests
+ From: test-first-workflow [project]
+ Confidence: 84%
+
+## AGENT CANDIDATES (1)
+ adding-tests-agent
+ Covers 3 instincts
+ Avg confidence: 82%
```
## Flags
-- `--execute`: Actually create the evolved structures (default is preview)
-- `--dry-run`: Preview without creating
-- `--domain <name>`: Only evolve instincts in specified domain
-- `--threshold <n>`: Minimum instincts required to form cluster (default: 3)
-- `--type <command|skill|agent>`: Only create specified type
+- `--generate`: Generate evolved files in addition to analysis output
## Generated File Format
diff --git a/commands/instinct-export.md b/commands/instinct-export.md
index a93f4e23e..6a47fa44c 100644
--- a/commands/instinct-export.md
+++ b/commands/instinct-export.md
@@ -1,6 +1,6 @@
---
name: instinct-export
-description: Export instincts for sharing with teammates or other projects
+description: Export instincts from project/global scope to a file
command: /instinct-export
---
@@ -18,17 +18,18 @@ Exports instincts to a shareable format. Perfect for:
/instinct-export --domain testing # Export only testing instincts
/instinct-export --min-confidence 0.7 # Only export high-confidence instincts
/instinct-export --output team-instincts.yaml
+/instinct-export --scope project --output project-instincts.yaml
```
## What to Do
-1. Read instincts from `~/.claude/homunculus/instincts/personal/`
-2. Filter based on flags
-3. Strip sensitive information:
- - Remove session IDs
- - Remove file paths (keep only patterns)
- - Remove timestamps older than "last week"
-4. Generate export file
+1. Detect current project context
+2. Load instincts by selected scope:
+ - `project`: current project only
+ - `global`: global only
+ - `all`: project + global merged (default)
+3. Apply filters (`--domain`, `--min-confidence`)
+4. Write YAML-style export to file (or stdout if no output path provided)
## Output Format
@@ -40,52 +41,26 @@ Creates a YAML file:
# Source: personal
# Count: 12 instincts
-version: "2.0"
-exported_by: "continuous-learning-v2"
-export_date: "2025-01-22T10:30:00Z"
-
-instincts:
- - id: prefer-functional-style
- trigger: "when writing new functions"
- action: "Use functional patterns over classes"
- confidence: 0.8
- domain: code-style
- observations: 8
+---
+id: prefer-functional-style
+trigger: "when writing new functions"
+confidence: 0.8
+domain: code-style
+source: session-observation
+scope: project
+project_id: a1b2c3d4e5f6
+project_name: my-app
+---
- - id: test-first-workflow
- trigger: "when adding new functionality"
- action: "Write test first, then implementation"
- confidence: 0.9
- domain: testing
- observations: 12
+# Prefer Functional Style
- - id: grep-before-edit
- trigger: "when modifying code"
- action: "Search with Grep, confirm with Read, then Edit"
- confidence: 0.7
- domain: workflow
- observations: 6
+## Action
+Use functional patterns over classes.
```
-## Privacy Considerations
-
-Exports include:
-- ✅ Trigger patterns
-- ✅ Actions
-- ✅ Confidence scores
-- ✅ Domains
-- ✅ Observation counts
-
-Exports do NOT include:
-- ❌ Actual code snippets
-- ❌ File paths
-- ❌ Session transcripts
-- ❌ Personal identifiers
-
## Flags
- `--domain <name>`: Export only specified domain
-- `--min-confidence <n>`: Minimum confidence threshold (default: 0.3)
-- `--output <file>`: Output file path (default: instincts-export-YYYYMMDD.yaml)
-- `--format <yaml|json|md>`: Output format (default: yaml)
-- `--include-evidence`: Include evidence text (default: excluded)
+- `--min-confidence <n>`: Minimum confidence threshold
+- `--output <file>`: Output file path (prints to stdout when omitted)
+- `--scope <project|global|all>`: Export scope (default: `all`)
diff --git a/commands/instinct-import.md b/commands/instinct-import.md
index 0dea62bad..f56f7fb81 100644
--- a/commands/instinct-import.md
+++ b/commands/instinct-import.md
@@ -1,6 +1,6 @@
---
name: instinct-import
-description: Import instincts from teammates, Skill Creator, or other sources
+description: Import instincts from file or URL into project/global scope
command: true
---
@@ -11,7 +11,7 @@ command: true
Run the instinct CLI using the plugin root path:
```bash
-python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" import <file-or-url> [--dry-run] [--force] [--min-confidence 0.7]
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" import <file-or-url> [--dry-run] [--force] [--min-confidence 0.7] [--scope project|global]
```
Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
@@ -20,18 +20,15 @@ Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py import <file-or-url>
```
-Import instincts from:
-- Teammates' exports
-- Skill Creator (repo analysis)
-- Community collections
-- Previous machine backups
+Import instincts from local file paths or HTTP(S) URLs.
## Usage
```
/instinct-import team-instincts.yaml
/instinct-import https://github.com/org/repo/instincts.yaml
-/instinct-import --from-skill-creator acme/webapp
+/instinct-import team-instincts.yaml --dry-run
+/instinct-import team-instincts.yaml --scope global --force
```
## What to Do
@@ -40,7 +37,9 @@ Import instincts from:
2. Parse and validate the format
3. Check for duplicates with existing instincts
4. Merge or add new instincts
-5. Save to `~/.claude/homunculus/instincts/inherited/`
+5. Save to inherited instincts directory:
+ - Project scope: `~/.claude/homunculus/projects/<project-id>/instincts/inherited/`
+ - Global scope: `~/.claude/homunculus/instincts/inherited/`
## Import Process
@@ -71,60 +70,33 @@ Already have similar instincts:
Import: 0.9 confidence
→ Update to import (higher confidence)
-## Conflicting Instincts (1)
-These contradict local instincts:
- ❌ use-classes-for-services
- Conflicts with: avoid-classes
- → Skip (requires manual resolution)
-
----
-Import 8 new, update 1, skip 3?
+Import 8 new, update 1?
```
-## Merge Strategies
-
-### For Duplicates
-When importing an instinct that matches an existing one:
-- **Higher confidence wins**: Keep the one with higher confidence
-- **Merge evidence**: Combine observation counts
-- **Update timestamp**: Mark as recently validated
+## Merge Behavior
-### For Conflicts
-When importing an instinct that contradicts an existing one:
-- **Skip by default**: Don't import conflicting instincts
-- **Flag for review**: Mark both as needing attention
-- **Manual resolution**: User decides which to keep
+When importing an instinct with an existing ID:
+- Higher-confidence import becomes an update candidate
+- Equal/lower-confidence import is skipped
+- User confirms unless `--force` is used
## Source Tracking
Imported instincts are marked with:
```yaml
-source: "inherited"
+source: inherited
+scope: project
imported_from: "team-instincts.yaml"
-imported_at: "2025-01-22T10:30:00Z"
-original_source: "session-observation" # or "repo-analysis"
+project_id: "a1b2c3d4e5f6"
+project_name: "my-project"
```
-## Skill Creator Integration
-
-When importing from Skill Creator:
-
-```
-/instinct-import --from-skill-creator acme/webapp
-```
-
-This fetches instincts generated from repo analysis:
-- Source: `repo-analysis`
-- Higher initial confidence (0.7+)
-- Linked to source repository
-
## Flags
- `--dry-run`: Preview without importing
-- `--force`: Import even if conflicts exist
-- `--merge-strategy <higher|local|import>`: How to handle duplicates
-- `--from-skill-creator <owner/repo>`: Import from Skill Creator analysis
+- `--force`: Skip confirmation prompt
- `--min-confidence <n>`: Only import instincts above threshold
+- `--scope <project|global>`: Select target scope (default: `project`)
## Output
@@ -134,7 +106,7 @@ After import:
Added: 8 instincts
Updated: 1 instinct
-Skipped: 3 instincts (2 duplicates, 1 conflict)
+Skipped: 3 instincts (equal/higher confidence already exists)
New instincts saved to: ~/.claude/homunculus/instincts/inherited/
diff --git a/commands/instinct-status.md b/commands/instinct-status.md
index 346ed4763..c54f80222 100644
--- a/commands/instinct-status.md
+++ b/commands/instinct-status.md
@@ -1,12 +1,12 @@
---
name: instinct-status
-description: Show all learned instincts with their confidence levels
+description: Show learned instincts (project + global) with confidence
command: true
---
# Instinct Status Command
-Shows all learned instincts with their confidence scores, grouped by domain.
+Shows learned instincts for the current project plus global instincts, grouped by domain.
## Implementation
@@ -26,61 +26,34 @@ python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
```
/instinct-status
-/instinct-status --domain code-style
-/instinct-status --low-confidence
```
## What to Do
-1. Read all instinct files from `~/.claude/homunculus/instincts/personal/`
-2. Read inherited instincts from `~/.claude/homunculus/instincts/inherited/`
-3. Display them grouped by domain with confidence bars
+1. Detect current project context (git remote/path hash)
+2. Read project instincts from `~/.claude/homunculus/projects/<project-id>/instincts/`
+3. Read global instincts from `~/.claude/homunculus/instincts/`
+4. Merge with precedence rules (project overrides global when IDs collide)
+5. Display grouped by domain with confidence bars and observation stats
## Output Format
```
-📊 Instinct Status
-==================
-
-## Code Style (4 instincts)
-
-### prefer-functional-style
-Trigger: when writing new functions
-Action: Use functional patterns over classes
-Confidence: ████████░░ 80%
-Source: session-observation | Last updated: 2025-01-22
-
-### use-path-aliases
-Trigger: when importing modules
-Action: Use @/ path aliases instead of relative imports
-Confidence: ██████░░░░ 60%
-Source: repo-analysis (github.com/acme/webapp)
-
-## Testing (2 instincts)
-
-### test-first-workflow
-Trigger: when adding new functionality
-Action: Write test first, then implementation
-Confidence: █████████░ 90%
-Source: session-observation
-
-## Workflow (3 instincts)
-
-### grep-before-edit
-Trigger: when modifying code
-Action: Search with Grep, confirm with Read, then Edit
-Confidence: ███████░░░ 70%
-Source: session-observation
-
----
-Total: 9 instincts (4 personal, 5 inherited)
-Observer: Running (last analysis: 5 min ago)
+============================================================
+ INSTINCT STATUS - 12 total
+============================================================
+
+ Project: my-app (a1b2c3d4e5f6)
+ Project instincts: 8
+ Global instincts: 4
+
+## PROJECT-SCOPED (my-app)
+ ### WORKFLOW (3)
+ ███████░░░ 70% grep-before-edit [project]
+ trigger: when modifying code
+
+## GLOBAL (apply to all projects)
+ ### SECURITY (2)
+ █████████░ 85% validate-user-input [global]
+ trigger: when handling user input
```
-
-## Flags
-
-- `--domain <name>`: Filter by domain (code-style, testing, git, etc.)
-- `--low-confidence`: Show only instincts with confidence < 0.5
-- `--high-confidence`: Show only instincts with confidence >= 0.7
-- `--source <type>`: Filter by source (session-observation, repo-analysis, inherited)
-- `--json`: Output as JSON for programmatic use
diff --git a/commands/projects.md b/commands/projects.md
new file mode 100644
index 000000000..8fa924eae
--- /dev/null
+++ b/commands/projects.md
@@ -0,0 +1,40 @@
+---
+name: projects
+description: List known projects and their instinct statistics
+command: true
+---
+
+# Projects Command
+
+List project registry entries and per-project instinct/observation counts for continuous-learning-v2.
+
+## Implementation
+
+Run the instinct CLI using the plugin root path:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" projects
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py projects
+```
+
+## Usage
+
+```bash
+/projects
+```
+
+## What to Do
+
+1. Read `~/.claude/homunculus/projects.json`
+2. For each project, display:
+ - Project name, id, root, remote
+ - Personal and inherited instinct counts
+ - Observation event count
+ - Last seen timestamp
+3. Also display global instinct totals
+
diff --git a/commands/promote.md b/commands/promote.md
new file mode 100644
index 000000000..4f02e27de
--- /dev/null
+++ b/commands/promote.md
@@ -0,0 +1,42 @@
+---
+name: promote
+description: Promote project-scoped instincts to global scope
+command: true
+---
+
+# Promote Command
+
+Promote instincts from project scope to global scope in continuous-learning-v2.
+
+## Implementation
+
+Run the instinct CLI using the plugin root path:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" promote [instinct-id] [--force] [--dry-run]
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py promote [instinct-id] [--force] [--dry-run]
+```
+
+## Usage
+
+```bash
+/promote # Auto-detect promotion candidates
+/promote --dry-run # Preview auto-promotion candidates
+/promote --force # Promote all qualified candidates without prompt
+/promote grep-before-edit # Promote one specific instinct from current project
+```
+
+## What to Do
+
+1. Detect current project
+2. If `instinct-id` is provided, promote only that instinct (if present in current project)
+3. Otherwise, find cross-project candidates that:
+ - Appear in at least 2 projects
+ - Meet confidence threshold
+4. Write promoted instincts to `~/.claude/homunculus/instincts/personal/` with `scope: global`
+
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 26c8e6d72..7ff868a80 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -37,7 +37,7 @@
"hooks": [
{
"type": "command",
- "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/pre-write-doc-warn.js\""
+ "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/\\.(md|txt)$/.test(p)&&!/(README|CLAUDE|AGENTS|CONTRIBUTING|CHANGELOG|LICENSE|SKILL)\\.md$/i.test(p)&&!/\\.claude[\\/\\\\]plans[\\/\\\\]/.test(p)&&!/(^|[\\/\\\\])(docs|skills)[\\/\\\\]/.test(p)){console.error('[Hook] WARNING: Non-standard documentation file detected');console.error('[Hook] File: '+p);console.error('[Hook] Consider consolidating into README.md or docs/ directory')}}catch{}console.log(d)})\""
}
],
"description": "Doc file warning: warn about non-standard documentation files (exit code 0; warns only)"
@@ -51,6 +51,18 @@
}
],
"description": "Suggest manual compaction at logical intervals"
+ },
+ {
+ "matcher": "*",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh",
+ "async": true,
+ "timeout": 10
+ }
+ ],
+ "description": "Capture tool use observations for continuous learning"
}
],
"PreCompact": [
@@ -129,6 +141,18 @@
}
],
"description": "Warn about console.log statements after edits"
+ },
+ {
+ "matcher": "*",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh",
+ "async": true,
+ "timeout": 10
+ }
+ ],
+ "description": "Capture tool use results for continuous learning"
}
],
"Stop": [
diff --git a/skills/continuous-learning-v2/SKILL.md b/skills/continuous-learning-v2/SKILL.md
index 8e2563869..ee1b3391c 100644
--- a/skills/continuous-learning-v2/SKILL.md
+++ b/skills/continuous-learning-v2/SKILL.md
@@ -1,15 +1,16 @@
---
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.
+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: ECC
-version: 2.0.0
+version: 2.1.0
---
-# Continuous Learning v2 - Instinct-Based Architecture
+# 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.
-Inspired in part by the Homunculus work from [humanplane](https://github.com/humanplane).
+**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
@@ -18,8 +19,21 @@ Inspired in part by the Homunculus work from [humanplane](https://github.com/hum
- 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
+## What's New in v2.1
+
+| Feature | v2.0 | v2.1 |
+|---------|------|------|
+| Storage | Global (~/.claude/homunculus/) | Project-scoped (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 |
|---------|----|----|
@@ -27,7 +41,7 @@ Inspired in part by the Homunculus work from [humanplane](https://github.com/hum
| 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 |
+| Evolution | Direct to skill | Instincts -> cluster -> skill/command/agent |
| Sharing | None | Export/import instincts |
## The Instinct Model
@@ -41,6 +55,9 @@ 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
@@ -54,51 +71,69 @@ Use functional patterns over classes when appropriate.
```
**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
+- **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
- │
- │ Hooks capture prompts + tool use (100% reliable)
- ▼
-┌─────────────────────────────────────────┐
-│ observations.jsonl │
-│ (prompts, tool calls, outcomes) │
-└─────────────────────────────────────────┘
- │
- │ Observer agent reads (background, Haiku)
- ▼
-┌─────────────────────────────────────────┐
-│ PATTERN DETECTION │
-│ • User corrections → instinct │
-│ • Error resolutions → instinct │
-│ • Repeated workflows → instinct │
-└─────────────────────────────────────────┘
- │
- │ Creates/updates
- ▼
-┌─────────────────────────────────────────┐
-│ instincts/personal/ │
-│ • prefer-functional.md (0.7) │
-│ • always-test-first.md (0.9) │
-│ • use-zod-validation.md (0.6) │
-└─────────────────────────────────────────┘
- │
- │ /evolve clusters
- ▼
-┌─────────────────────────────────────────┐
-│ evolved/ │
-│ • commands/new-feature.md │
-│ • skills/testing-workflow.md │
-│ • agents/refactor-specialist.md │
-└─────────────────────────────────────────┘
+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 `~/.claude/homunculus/projects.json` maps IDs to human-readable names.
+
## Quick Start
### 1. Enable Observation Hooks
@@ -114,14 +149,14 @@ Add to your `~/.claude/settings.json`.
"matcher": "*",
"hooks": [{
"type": "command",
- "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh pre"
+ "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh"
}]
}],
"PostToolUse": [{
"matcher": "*",
"hooks": [{
"type": "command",
- "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh post"
+ "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh"
}]
}]
}
@@ -137,14 +172,14 @@ Add to your `~/.claude/settings.json`.
"matcher": "*",
"hooks": [{
"type": "command",
- "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh pre"
+ "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
}]
}],
"PostToolUse": [{
"matcher": "*",
"hooks": [{
"type": "command",
- "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh post"
+ "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
}]
}]
}
@@ -153,92 +188,124 @@ Add to your `~/.claude/settings.json`.
### 2. Initialize Directory Structure
-The Python CLI will create these automatically, but you can also create them manually:
+The system creates directories automatically on first use, but you can also create them manually:
```bash
-mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands}}
-touch ~/.claude/homunculus/observations.jsonl
+# Global directories
+mkdir -p ~/.claude/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 with confidence scores
+/instinct-status # Show learned instincts (project + global)
/evolve # Cluster related instincts into skills/commands
-/instinct-export # Export instincts for sharing
+/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 learned instincts with confidence |
-| `/evolve` | Cluster related instincts into skills/commands |
-| `/instinct-export` | Export instincts for sharing |
-| `/instinct-import <file>` | Import instincts from others |
+| `/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`:
+Edit `config.json` to control the background observer:
```json
{
- "version": "2.0",
- "observation": {
- "enabled": true,
- "store_path": "~/.claude/homunculus/observations.jsonl",
- "max_file_size_mb": 10,
- "archive_after_days": 7
- },
- "instincts": {
- "personal_path": "~/.claude/homunculus/instincts/personal/",
- "inherited_path": "~/.claude/homunculus/instincts/inherited/",
- "min_confidence": 0.3,
- "auto_approve_threshold": 0.7,
- "confidence_decay_rate": 0.05
- },
+ "version": "2.1",
"observer": {
- "enabled": true,
- "model": "haiku",
+ "enabled": false,
"run_interval_minutes": 5,
- "patterns_to_detect": [
- "user_corrections",
- "error_resolutions",
- "repeated_workflows",
- "tool_preferences"
- ]
- },
- "evolution": {
- "cluster_threshold": 3,
- "evolved_path": "~/.claude/homunculus/evolved/"
+ "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
```
~/.claude/homunculus/
-├── identity.json # Your profile, technical level
-├── observations.jsonl # Current session observations
-├── observations.archive/ # Processed observations
-├── instincts/
-│ ├── personal/ # Auto-learned instincts
-│ └── inherited/ # Imported from others
-└── evolved/
- ├── agents/ # Generated specialist agents
- ├── skills/ # Generated skills
- └── commands/ # Generated commands
++-- 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)
+ | +-- observations.jsonl
+ | +-- observations.archive/
+ | +-- instincts/
+ | | +-- personal/ # Project-specific auto-learned
+ | | +-- inherited/ # Project-specific imported
+ | +-- evolved/
+ | +-- skills/
+ | +-- commands/
+ | +-- agents/
+ +-- f6e5d4c3b2a1/ # Another project
+ +-- ...
```
-## Integration with Skill Creator
+## Scope Decision Guide
-When you use the [Skill Creator GitHub App](https://skill-creator.app), it now generates **both**:
-- Traditional SKILL.md files (for backward compatibility)
-- Instinct collections (for v2 learning system)
+| 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
+```
-Instincts from repo analysis have `source: "repo-analysis"` and include the source repository URL.
+The `/evolve` command also suggests promotion candidates.
## Confidence Scoring
@@ -263,7 +330,7 @@ Confidence evolves over time:
## 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."
+> "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
@@ -272,17 +339,19 @@ Hooks fire **100% of the time**, deterministically. This means:
## Backward Compatibility
-v2 is fully compatible with v1:
-- Existing `~/.claude/skills/learned/` skills still work
+v2.1 is fully compatible with v2.0 and v1:
+- Existing global instincts in `~/.claude/homunculus/instincts/` still work as global instincts
+- Existing `~/.claude/skills/learned/` skills from v1 still work
- Stop hook still runs (but now also feeds into v2)
-- Gradual migration path: run both in parallel
+- Gradual migration: run both in parallel
## Privacy
- Observations stay **local** on your machine
-- Only **instincts** (patterns) can be exported
+- 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
+- You control what gets exported and promoted
## Related
@@ -292,4 +361,4 @@ v2 is fully compatible with v1:
---
-*Instinct-based learning: teaching Claude your patterns, one observation at a time.*
+*Instinct-based learning: teaching Claude your patterns, one project at a time.*
diff --git a/skills/continuous-learning-v2/agents/observer.md b/skills/continuous-learning-v2/agents/observer.md
index 79bcd5340..81abb9c15 100644
--- 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+).
diff --git a/skills/continuous-learning-v2/agents/start-observer.sh b/skills/continuous-learning-v2/agents/start-observer.sh
index 6ba6f11f1..99b250992 100755
--- 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
+# ─────────────────────────────────────────────
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-mkdir -p "$CONFIG_DIR"
+# 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
diff --git a/skills/continuous-learning-v2/config.json b/skills/continuous-learning-v2/config.json
index 1f6e0c8d5..84f622095 100644
--- a/skills/continuous-learning-v2/config.json
+++ b/skills/continuous-learning-v2/config.json
@@ -1,41 +1,8 @@
{
- "version": "2.0",
- "observation": {
- "enabled": true,
- "store_path": "~/.claude/homunculus/observations.jsonl",
- "max_file_size_mb": 10,
- "archive_after_days": 7,
- "capture_tools": ["Edit", "Write", "Bash", "Read", "Grep", "Glob"],
- "ignore_tools": ["TodoWrite"]
- },
- "instincts": {
- "personal_path": "~/.claude/homunculus/instincts/personal/",
- "inherited_path": "~/.claude/homunculus/instincts/inherited/",
- "min_confidence": 0.3,
- "auto_approve_threshold": 0.7,
- "confidence_decay_rate": 0.02,
- "max_instincts": 100
- },
+ "version": "2.1",
"observer": {
"enabled": false,
- "model": "haiku",
"run_interval_minutes": 5,
- "min_observations_to_analyze": 20,
- "patterns_to_detect": [
- "user_corrections",
- "error_resolutions",
- "repeated_workflows",
- "tool_preferences",
- "file_patterns"
- ]
- },
- "evolution": {
- "cluster_threshold": 3,
- "evolved_path": "~/.claude/homunculus/evolved/",
- "auto_evolve": false
- },
- "integration": {
- "skill_creator_api": "https://skill-creator.app/api",
- "backward_compatible_v1": true
+ "min_observations_to_analyze": 20
}
}
diff --git a/skills/continuous-learning-v2/hooks/observe.sh b/skills/continuous-learning-v2/hooks/observe.sh
index 86cfb22b1..7f78f8018 100755
--- a/skills/continuous-learning-v2/hooks/observe.sh
+++ b/skills/continuous-learning-v2/hooks/observe.sh
@@ -4,52 +4,20 @@
# Captures tool use events for pattern analysis.
# Claude Code passes hook data via stdin as JSON.
#
-# Hook config (in ~/.claude/settings.json):
+# v2.1: Project-scoped observations — detects current project context
+# and writes observations to project-specific directory.
#
-# If installed as a plugin, use ${CLAUDE_PLUGIN_ROOT}:
-# {
-# "hooks": {
-# "PreToolUse": [{
-# "matcher": "*",
-# "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh pre" }]
-# }],
-# "PostToolUse": [{
-# "matcher": "*",
-# "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh post" }]
-# }]
-# }
-# }
-#
-# If installed manually to ~/.claude/skills:
-# {
-# "hooks": {
-# "PreToolUse": [{
-# "matcher": "*",
-# "hooks": [{ "type": "command", "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh pre" }]
-# }],
-# "PostToolUse": [{
-# "matcher": "*",
-# "hooks": [{ "type": "command", "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh post" }]
-# }]
-# }
-# }
+# Registered via plugin hooks/hooks.json (auto-loaded when plugin is enabled).
+# Can also be registered manually in ~/.claude/settings.json.
set -e
# Hook phase from CLI argument: "pre" (PreToolUse) or "post" (PostToolUse)
HOOK_PHASE="${1:-post}"
-CONFIG_DIR="${HOME}/.claude/homunculus"
-OBSERVATIONS_FILE="${CONFIG_DIR}/observations.jsonl"
-MAX_FILE_SIZE_MB=10
-
-# Ensure directory exists
-mkdir -p "$CONFIG_DIR"
-
-# Skip if disabled
-if [ -f "$CONFIG_DIR/disabled" ]; then
- exit 0
-fi
+# ─────────────────────────────────────────────
+# Read stdin first (before project detection)
+# ─────────────────────────────────────────────
# Read JSON from stdin (Claude Code hook format)
INPUT_JSON=$(cat)
@@ -59,6 +27,51 @@ if [ -z "$INPUT_JSON" ]; then
exit 0
fi
+# ─────────────────────────────────────────────
+# Extract cwd from stdin for project detection
+# ─────────────────────────────────────────────
+
+# Extract cwd from the hook JSON to use for project detection.
+# This avoids spawning a separate git subprocess when cwd is available.
+STDIN_CWD=$(echo "$INPUT_JSON" | python3 -c '
+import json, sys
+try:
+ data = json.load(sys.stdin)
+ cwd = data.get("cwd", "")
+ print(cwd)
+except(KeyError, TypeError, ValueError):
+ print("")
+' 2>/dev/null || echo "")
+
+# If cwd was provided in stdin, use it for project detection
+if [ -n "$STDIN_CWD" ] && [ -d "$STDIN_CWD" ]; then
+ export CLAUDE_PROJECT_DIR="$STDIN_CWD"
+fi
+
+# ─────────────────────────────────────────────
+# Project detection
+# ─────────────────────────────────────────────
+
+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"
+OBSERVATIONS_FILE="${PROJECT_DIR}/observations.jsonl"
+MAX_FILE_SIZE_MB=10
+
+# Skip if disabled
+if [ -f "$CONFIG_DIR/disabled" ]; then
+ exit 0
+fi
+
# Parse using python via stdin pipe (safe for all JSON payloads)
# Pass HOOK_PHASE via env var since Claude Code does not include hook type in stdin JSON
PARSED=$(echo "$INPUT_JSON" | HOOK_PHASE="$HOOK_PHASE" python3 -c '
@@ -80,6 +93,8 @@ try:
tool_input = data.get("tool_input", data.get("input", {}))
tool_output = data.get("tool_output", data.get("output", ""))
session_id = data.get("session_id", "unknown")
+ tool_use_id = data.get("tool_use_id", "")
+ cwd = data.get("cwd", "")
# Truncate large inputs/outputs
if isinstance(tool_input, dict):
@@ -88,24 +103,26 @@ try:
tool_input_str = str(tool_input)[:5000]
if isinstance(tool_output, dict):
- tool_output_str = json.dumps(tool_output)[:5000]
+ tool_response_str = json.dumps(tool_output)[:5000]
else:
- tool_output_str = str(tool_output)[:5000]
+ tool_response_str = str(tool_output)[:5000]
print(json.dumps({
"parsed": True,
"event": event,
"tool": tool_name,
"input": tool_input_str if event == "tool_start" else None,
- "output": tool_output_str if event == "tool_complete" else None,
- "session": session_id
+ "output": tool_response_str if event == "tool_complete" else None,
+ "session": session_id,
+ "tool_use_id": tool_use_id,
+ "cwd": cwd
}))
except Exception as e:
print(json.dumps({"parsed": False, "error": str(e)}))
')
# Check if parsing succeeded
-PARSED_OK=$(echo "$PARSED" | python3 -c "import json,sys; print(json.load(sys.stdin).get('parsed', False))")
+PARSED_OK=$(echo "$PARSED" | python3 -c "import json,sys; print(json.load(sys.stdin).get('parsed', False))" 2>/dev/null || echo "False")
if [ "$PARSED_OK" != "True" ]; then
# Fallback: log raw input for debugging
@@ -119,20 +136,23 @@ print(json.dumps({'timestamp': os.environ['TIMESTAMP'], 'event': 'parse_error',
exit 0
fi
-# Archive if file too large
+# Archive if file too large (atomic: rename with unique suffix to avoid race)
if [ -f "$OBSERVATIONS_FILE" ]; then
file_size_mb=$(du -m "$OBSERVATIONS_FILE" 2>/dev/null | cut -f1)
if [ "${file_size_mb:-0}" -ge "$MAX_FILE_SIZE_MB" ]; then
- archive_dir="${CONFIG_DIR}/observations.archive"
+ archive_dir="${PROJECT_DIR}/observations.archive"
mkdir -p "$archive_dir"
- mv "$OBSERVATIONS_FILE" "$archive_dir/observations-$(date +%Y%m%d-%H%M%S).jsonl"
+ mv "$OBSERVATIONS_FILE" "$archive_dir/observations-$(date +%Y%m%d-%H%M%S)-$$.jsonl" 2>/dev/null || true
fi
fi
-# Build and write observation
+# Build and write observation (now includes project context)
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+export PROJECT_ID_ENV="$PROJECT_ID"
+export PROJECT_NAME_ENV="$PROJECT_NAME"
export TIMESTAMP="$timestamp"
+
echo "$PARSED" | python3 -c "
import json, sys, os
@@ -141,10 +161,12 @@ observation = {
'timestamp': os.environ['TIMESTAMP'],
'event': parsed['event'],
'tool': parsed['tool'],
- 'session': parsed['session']
+ 'session': parsed['session'],
+ 'project_id': os.environ.get('PROJECT_ID_ENV', 'global'),
+ 'project_name': os.environ.get('PROJECT_NAME_ENV', 'global')
}
-if parsed['input'] is not None:
+if parsed['input']:
observation['input'] = parsed['input']
if parsed['output'] is not None:
observation['output'] = parsed['output']
@@ -152,13 +174,14 @@ if parsed['output'] is not None:
print(json.dumps(observation))
" >> "$OBSERVATIONS_FILE"
-# Signal observer if running
-OBSERVER_PID_FILE="${CONFIG_DIR}/.observer.pid"
-if [ -f "$OBSERVER_PID_FILE" ]; then
- observer_pid=$(cat "$OBSERVER_PID_FILE")
- if kill -0 "$observer_pid" 2>/dev/null; then
- kill -USR1 "$observer_pid" 2>/dev/null || true
+# Signal observer if running (check both project-scoped and global observer)
+for pid_file in "${PROJECT_DIR}/.observer.pid" "${CONFIG_DIR}/.observer.pid"; do
+ if [ -f "$pid_file" ]; then
+ observer_pid=$(cat "$pid_file")
+ if kill -0 "$observer_pid" 2>/dev/null; then
+ kill -USR1 "$observer_pid" 2>/dev/null || true
+ fi
fi
-fi
+done
exit 0
diff --git a/skills/continuous-learning-v2/scripts/detect-project.sh b/skills/continuous-learning-v2/scripts/detect-project.sh
new file mode 100755
index 000000000..31703a218
--- /dev/null
+++ b/skills/continuous-learning-v2/scripts/detect-project.sh
@@ -0,0 +1,141 @@
+#!/bin/bash
+# Continuous Learning v2 - Project Detection Helper
+#
+# Shared logic for detecting current project context.
+# Sourced by observe.sh and start-observer.sh.
+#
+# Exports:
+# _CLV2_PROJECT_ID - Short hash identifying the project (or "global")
+# _CLV2_PROJECT_NAME - Human-readable project name
+# _CLV2_PROJECT_ROOT - Absolute path to project root
+# _CLV2_PROJECT_DIR - Project-scoped storage directory under homunculus
+#
+# Also sets unprefixed convenience aliases:
+# PROJECT_ID, PROJECT_NAME, PROJECT_ROOT, PROJECT_DIR
+#
+# Detection priority:
+# 1. CLAUDE_PROJECT_DIR env var (if set)
+# 2. git remote URL (hashed for uniqueness across machines)
+# 3. git repo root path (fallback, machine-specific)
+# 4. "global" (no project context detected)
+
+_CLV2_HOMUNCULUS_DIR="${HOME}/.claude/homunculus"
+_CLV2_PROJECTS_DIR="${_CLV2_HOMUNCULUS_DIR}/projects"
+_CLV2_REGISTRY_FILE="${_CLV2_HOMUNCULUS_DIR}/projects.json"
+
+_clv2_detect_project() {
+ local project_root=""
+ local project_name=""
+ local project_id=""
+ local source_hint=""
+
+ # 1. Try CLAUDE_PROJECT_DIR env var
+ if [ -n "$CLAUDE_PROJECT_DIR" ] && [ -d "$CLAUDE_PROJECT_DIR" ]; then
+ project_root="$CLAUDE_PROJECT_DIR"
+ source_hint="env"
+ fi
+
+ # 2. Try git repo root from CWD (only if git is available)
+ if [ -z "$project_root" ] && command -v git &>/dev/null; then
+ project_root=$(git rev-parse --show-toplevel 2>/dev/null || true)
+ if [ -n "$project_root" ]; then
+ source_hint="git"
+ fi
+ fi
+
+ # 3. No project detected — fall back to global
+ if [ -z "$project_root" ]; then
+ _CLV2_PROJECT_ID="global"
+ _CLV2_PROJECT_NAME="global"
+ _CLV2_PROJECT_ROOT=""
+ _CLV2_PROJECT_DIR="${_CLV2_HOMUNCULUS_DIR}"
+ return 0
+ fi
+
+ # Derive project name from directory basename
+ project_name=$(basename "$project_root")
+
+ # Derive project ID: prefer git remote URL hash (portable across machines),
+ # fall back to path hash (machine-specific but still useful)
+ local remote_url=""
+ if command -v git &>/dev/null; then
+ if [ "$source_hint" = "git" ] || [ -d "${project_root}/.git" ]; then
+ remote_url=$(git -C "$project_root" remote get-url origin 2>/dev/null || true)
+ fi
+ fi
+
+ local hash_input="${remote_url:-$project_root}"
+ # Use SHA256 via python3 (portable across macOS/Linux, no shasum/sha256sum divergence)
+ project_id=$(printf '%s' "$hash_input" | python3 -c "import sys,hashlib; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest()[:12])" 2>/dev/null)
+
+ # Fallback if python3 failed
+ if [ -z "$project_id" ]; then
+ project_id=$(printf '%s' "$hash_input" | shasum -a 256 2>/dev/null | cut -c1-12 || \
+ printf '%s' "$hash_input" | sha256sum 2>/dev/null | cut -c1-12 || \
+ echo "fallback")
+ fi
+
+ # Export results
+ _CLV2_PROJECT_ID="$project_id"
+ _CLV2_PROJECT_NAME="$project_name"
+ _CLV2_PROJECT_ROOT="$project_root"
+ _CLV2_PROJECT_DIR="${_CLV2_PROJECTS_DIR}/${project_id}"
+
+ # Ensure project directory structure exists
+ mkdir -p "${_CLV2_PROJECT_DIR}/instincts/personal"
+ mkdir -p "${_CLV2_PROJECT_DIR}/instincts/inherited"
+ mkdir -p "${_CLV2_PROJECT_DIR}/observations.archive"
+ mkdir -p "${_CLV2_PROJECT_DIR}/evolved/skills"
+ mkdir -p "${_CLV2_PROJECT_DIR}/evolved/commands"
+ mkdir -p "${_CLV2_PROJECT_DIR}/evolved/agents"
+
+ # Update project registry (lightweight JSON mapping)
+ _clv2_update_project_registry "$project_id" "$project_name" "$project_root" "$remote_url"
+}
+
+_clv2_update_project_registry() {
+ local pid="$1"
+ local pname="$2"
+ local proot="$3"
+ local premote="$4"
+
+ mkdir -p "$(dirname "$_CLV2_REGISTRY_FILE")"
+
+ # Pass values via env vars to avoid shell→python injection.
+ # python3 reads them with os.environ, which is safe for any string content.
+ _CLV2_REG_PID="$pid" \
+ _CLV2_REG_PNAME="$pname" \
+ _CLV2_REG_PROOT="$proot" \
+ _CLV2_REG_PREMOTE="$premote" \
+ _CLV2_REG_FILE="$_CLV2_REGISTRY_FILE" \
+ python3 -c '
+import json, os
+from datetime import datetime, timezone
+
+registry_path = os.environ["_CLV2_REG_FILE"]
+try:
+ with open(registry_path) as f:
+ registry = json.load(f)
+except (FileNotFoundError, json.JSONDecodeError):
+ registry = {}
+
+registry[os.environ["_CLV2_REG_PID"]] = {
+ "name": os.environ["_CLV2_REG_PNAME"],
+ "root": os.environ["_CLV2_REG_PROOT"],
+ "remote": os.environ["_CLV2_REG_PREMOTE"],
+ "last_seen": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+}
+
+with open(registry_path, "w") as f:
+ json.dump(registry, f, indent=2)
+' 2>/dev/null || true
+}
+
+# Auto-detect on source
+_clv2_detect_project
+
+# Convenience aliases for callers (short names pointing to prefixed vars)
+PROJECT_ID="$_CLV2_PROJECT_ID"
+PROJECT_NAME="$_CLV2_PROJECT_NAME"
+PROJECT_ROOT="$_CLV2_PROJECT_ROOT"
+PROJECT_DIR="$_CLV2_PROJECT_DIR"
diff --git a/skills/continuous-learning-v2/scripts/instinct-cli.py b/skills/continuous-learning-v2/scripts/instinct-cli.py
index ed6c376b1..0d0192b9f 100755
--- a/skills/continuous-learning-v2/scripts/instinct-cli.py
+++ b/skills/continuous-learning-v2/scripts/instinct-cli.py
@@ -2,21 +2,28 @@
"""
Instinct CLI - Manage instincts for Continuous Learning v2
+v2.1: Project-scoped instincts — different projects get different instincts,
+ with global instincts applied universally.
+
Commands:
- status - Show all instincts and their status
+ status - Show all instincts (project + global) and their status
import - Import instincts from file or URL
export - Export instincts to file
evolve - Cluster instincts into skills/commands/agents
+ promote - Promote project instincts to global scope
+ projects - List all known projects and their instinct counts
"""
import argparse
import json
+import hashlib
import os
+import subprocess
import sys
import re
import urllib.request
from pathlib import Path
-from datetime import datetime
+from datetime import datetime, timezone
from collections import defaultdict
from typing import Optional
@@ -25,15 +32,188 @@ from typing import Optional
# ─────────────────────────────────────────────
HOMUNCULUS_DIR = Path.home() / ".claude" / "homunculus"
-INSTINCTS_DIR = HOMUNCULUS_DIR / "instincts"
-PERSONAL_DIR = INSTINCTS_DIR / "personal"
-INHERITED_DIR = INSTINCTS_DIR / "inherited"
-EVOLVED_DIR = HOMUNCULUS_DIR / "evolved"
-OBSERVATIONS_FILE = HOMUNCULUS_DIR / "observations.jsonl"
+PROJECTS_DIR = HOMUNCULUS_DIR / "projects"
+REGISTRY_FILE = HOMUNCULUS_DIR / "projects.json"
+
+# Global (non-project-scoped) paths
+GLOBAL_INSTINCTS_DIR = HOMUNCULUS_DIR / "instincts"
+GLOBAL_PERSONAL_DIR = GLOBAL_INSTINCTS_DIR / "personal"
+GLOBAL_INHERITED_DIR = GLOBAL_INSTINCTS_DIR / "inherited"
+GLOBAL_EVOLVED_DIR = HOMUNCULUS_DIR / "evolved"
+GLOBAL_OBSERVATIONS_FILE = HOMUNCULUS_DIR / "observations.jsonl"
+
+# Thresholds for auto-promotion
+PROMOTE_CONFIDENCE_THRESHOLD = 0.8
+PROMOTE_MIN_PROJECTS = 2
+ALLOWED_INSTINCT_EXTENSIONS = (".yaml", ".yml", ".md")
+
+# Ensure global directories exist (deferred to avoid side effects at import time)
+def _ensure_global_dirs():
+ for d in [GLOBAL_PERSONAL_DIR, GLOBAL_INHERITED_DIR,
+ GLOBAL_EVOLVED_DIR / "skills", GLOBAL_EVOLVED_DIR / "commands", GLOBAL_EVOLVED_DIR / "agents",
+ PROJECTS_DIR]:
+ d.mkdir(parents=True, exist_ok=True)
+
+
+# ─────────────────────────────────────────────
+# Path Validation
+# ─────────────────────────────────────────────
+
+def _validate_file_path(path_str: str, must_exist: bool = False) -> Path:
+ """Validate and resolve a file path, guarding against path traversal.
+
+ Raises ValueError if the path is invalid or suspicious.
+ """
+ path = Path(path_str).expanduser().resolve()
+
+ # Block paths that escape into system directories
+ # We block specific system paths but allow temp dirs (/var/folders on macOS)
+ blocked_prefixes = [
+ "/etc", "/usr", "/bin", "/sbin", "/proc", "/sys",
+ "/var/log", "/var/run", "/var/lib", "/var/spool",
+ # macOS resolves /etc → /private/etc
+ "/private/etc",
+ "/private/var/log", "/private/var/run", "/private/var/db",
+ ]
+ path_s = str(path)
+ for prefix in blocked_prefixes:
+ if path_s.startswith(prefix + "/") or path_s == prefix:
+ raise ValueError(f"Path '{path}' targets a system directory")
+
+ if must_exist and not path.exists():
+ raise ValueError(f"Path does not exist: {path}")
+
+ return path
+
+
+def _validate_instinct_id(instinct_id: str) -> bool:
+ """Validate instinct IDs before using them in filenames."""
+ if not instinct_id or len(instinct_id) > 128:
+ return False
+ if "/" in instinct_id or "\\" in instinct_id:
+ return False
+ if ".." in instinct_id:
+ return False
+ if instinct_id.startswith("."):
+ return False
+ return bool(re.match(r"^[A-Za-z0-9][A-Za-z0-9._-]*$", instinct_id))
+
-# Ensure directories exist
-for d in [PERSONAL_DIR, INHERITED_DIR, EVOLVED_DIR / "skills", EVOLVED_DIR / "commands", EVOLVED_DIR / "agents"]:
- d.mkdir(parents=True, exist_ok=True)
+# ─────────────────────────────────────────────
+# Project Detection (Python equivalent of detect-project.sh)
+# ─────────────────────────────────────────────
+
+def detect_project() -> dict:
+ """Detect current project context. Returns dict with id, name, root, project_dir."""
+ project_root = None
+
+ # 1. CLAUDE_PROJECT_DIR env var
+ env_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+ if env_dir and os.path.isdir(env_dir):
+ project_root = env_dir
+
+ # 2. git repo root
+ if not project_root:
+ try:
+ result = subprocess.run(
+ ["git", "rev-parse", "--show-toplevel"],
+ capture_output=True, text=True, timeout=5
+ )
+ if result.returncode == 0:
+ project_root = result.stdout.strip()
+ except (subprocess.TimeoutExpired, FileNotFoundError):
+ pass
+
+ # 3. No project — global fallback
+ if not project_root:
+ return {
+ "id": "global",
+ "name": "global",
+ "root": "",
+ "project_dir": HOMUNCULUS_DIR,
+ "instincts_personal": GLOBAL_PERSONAL_DIR,
+ "instincts_inherited": GLOBAL_INHERITED_DIR,
+ "evolved_dir": GLOBAL_EVOLVED_DIR,
+ "observations_file": GLOBAL_OBSERVATIONS_FILE,
+ }
+
+ project_name = os.path.basename(project_root)
+
+ # Derive project ID from git remote URL or path
+ remote_url = ""
+ try:
+ result = subprocess.run(
+ ["git", "-C", project_root, "remote", "get-url", "origin"],
+ capture_output=True, text=True, timeout=5
+ )
+ if result.returncode == 0:
+ remote_url = result.stdout.strip()
+ except (subprocess.TimeoutExpired, FileNotFoundError):
+ pass
+
+ hash_source = remote_url if remote_url else project_root
+ project_id = hashlib.sha256(hash_source.encode()).hexdigest()[:12]
+
+ project_dir = PROJECTS_DIR / project_id
+
+ # Ensure project directory structure
+ for d in [
+ project_dir / "instincts" / "personal",
+ project_dir / "instincts" / "inherited",
+ project_dir / "observations.archive",
+ project_dir / "evolved" / "skills",
+ project_dir / "evolved" / "commands",
+ project_dir / "evolved" / "agents",
+ ]:
+ d.mkdir(parents=True, exist_ok=True)
+
+ # Update registry
+ _update_registry(project_id, project_name, project_root, remote_url)
+
+ return {
+ "id": project_id,
+ "name": project_name,
+ "root": project_root,
+ "remote": remote_url,
+ "project_dir": project_dir,
+ "instincts_personal": project_dir / "instincts" / "personal",
+ "instincts_inherited": project_dir / "instincts" / "inherited",
+ "evolved_dir": project_dir / "evolved",
+ "observations_file": project_dir / "observations.jsonl",
+ }
+
+
+def _update_registry(pid: str, pname: str, proot: str, premote: str) -> None:
+ """Update the projects.json registry."""
+ try:
+ with open(REGISTRY_FILE) as f:
+ registry = json.load(f)
+ except (FileNotFoundError, json.JSONDecodeError):
+ registry = {}
+
+ registry[pid] = {
+ "name": pname,
+ "root": proot,
+ "remote": premote,
+ "last_seen": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+ }
+
+ REGISTRY_FILE.parent.mkdir(parents=True, exist_ok=True)
+ tmp_file = REGISTRY_FILE.parent / f".{REGISTRY_FILE.name}.tmp.{os.getpid()}"
+ with open(tmp_file, "w") as f:
+ json.dump(registry, f, indent=2)
+ f.flush()
+ os.fsync(f.fileno())
+ os.replace(tmp_file, REGISTRY_FILE)
+
+
+def load_registry() -> dict:
+ """Load the projects registry."""
+ try:
+ with open(REGISTRY_FILE) as f:
+ return json.load(f)
+ except (FileNotFoundError, json.JSONDecodeError):
+ return {}
# ─────────────────────────────────────────────
@@ -81,107 +261,180 @@ def parse_instinct_file(content: str) -> list[dict]:
return [i for i in instincts if i.get('id')]
-def load_all_instincts() -> list[dict]:
- """Load all instincts from personal and inherited directories."""
+def _load_instincts_from_dir(directory: Path, source_type: str, scope_label: str) -> list[dict]:
+ """Load instincts from a single directory."""
+ instincts = []
+ if not directory.exists():
+ return instincts
+ files = [
+ file for file in sorted(directory.iterdir())
+ if file.is_file() and file.suffix.lower() in ALLOWED_INSTINCT_EXTENSIONS
+ ]
+ for file in files:
+ try:
+ content = file.read_text()
+ parsed = parse_instinct_file(content)
+ for inst in parsed:
+ inst['_source_file'] = str(file)
+ inst['_source_type'] = source_type
+ inst['_scope_label'] = scope_label
+ # Default scope if not set in frontmatter
+ if 'scope' not in inst:
+ inst['scope'] = scope_label
+ instincts.extend(parsed)
+ except Exception as e:
+ print(f"Warning: Failed to parse {file}: {e}", file=sys.stderr)
+ return instincts
+
+
+def load_all_instincts(project: dict, include_global: bool = True) -> list[dict]:
+ """Load all instincts: project-scoped + global.
+
+ Project-scoped instincts take precedence over global ones when IDs conflict.
+ """
instincts = []
- for directory in [PERSONAL_DIR, INHERITED_DIR]:
- if not directory.exists():
- continue
- yaml_files = sorted(
- set(directory.glob("*.yaml"))
- | set(directory.glob("*.yml"))
- | set(directory.glob("*.md"))
- )
- for file in yaml_files:
- try:
- content = file.read_text()
- parsed = parse_instinct_file(content)
- for inst in parsed:
- inst['_source_file'] = str(file)
- inst['_source_type'] = directory.name
- instincts.extend(parsed)
- except Exception as e:
- print(f"Warning: Failed to parse {file}: {e}", file=sys.stderr)
+ # 1. Load project-scoped instincts (if not already global)
+ if project["id"] != "global":
+ instincts.extend(_load_instincts_from_dir(
+ project["instincts_personal"], "personal", "project"
+ ))
+ instincts.extend(_load_instincts_from_dir(
+ project["instincts_inherited"], "inherited", "project"
+ ))
+
+ # 2. Load global instincts
+ if include_global:
+ global_instincts = []
+ global_instincts.extend(_load_instincts_from_dir(
+ GLOBAL_PERSONAL_DIR, "personal", "global"
+ ))
+ global_instincts.extend(_load_instincts_from_dir(
+ GLOBAL_INHERITED_DIR, "inherited", "global"
+ ))
+
+ # Deduplicate: project-scoped wins over global when same ID
+ project_ids = {i.get('id') for i in instincts}
+ for gi in global_instincts:
+ if gi.get('id') not in project_ids:
+ instincts.append(gi)
return instincts
+def load_project_only_instincts(project: dict) -> list[dict]:
+ """Load only project-scoped instincts (no global).
+
+ In global fallback mode (no git project), returns global instincts.
+ """
+ if project.get("id") == "global":
+ instincts = _load_instincts_from_dir(GLOBAL_PERSONAL_DIR, "personal", "global")
+ instincts += _load_instincts_from_dir(GLOBAL_INHERITED_DIR, "inherited", "global")
+ return instincts
+ return load_all_instincts(project, include_global=False)
+
+
# ─────────────────────────────────────────────
# Status Command
# ─────────────────────────────────────────────
-def cmd_status(args):
- """Show status of all instincts."""
- instincts = load_all_instincts()
+def cmd_status(args) -> int:
+ """Show status of all instincts (project + global)."""
+ project = detect_project()
+ instincts = load_all_instincts(project)
if not instincts:
print("No instincts found.")
- print(f"\nInstinct directories:")
- print(f" Personal: {PERSONAL_DIR}")
- print(f" Inherited: {INHERITED_DIR}")
- return
+ print(f"\nProject: {project['name']} ({project['id']})")
+ print(f" Project instincts: {project['instincts_personal']}")
+ print(f" Global instincts: {GLOBAL_PERSONAL_DIR}")
+ return 0
- # Group by domain
- by_domain = defaultdict(list)
- for inst in instincts:
- domain = inst.get('domain', 'general')
- by_domain[domain].append(inst)
+ # Split by scope
+ project_instincts = [i for i in instincts if i.get('_scope_label') == 'project']
+ global_instincts = [i for i in instincts if i.get('_scope_label') == 'global']
# Print header
print(f"\n{'='*60}")
print(f" INSTINCT STATUS - {len(instincts)} total")
print(f"{'='*60}\n")
- # Summary by source
- personal = [i for i in instincts if i.get('_source_type') == 'personal']
- inherited = [i for i in instincts if i.get('_source_type') == 'inherited']
- print(f" Personal: {len(personal)}")
- print(f" Inherited: {len(inherited)}")
+ print(f" Project: {project['name']} ({project['id']})")
+ print(f" Project instincts: {len(project_instincts)}")
+ print(f" Global instincts: {len(global_instincts)}")
print()
- # Print by domain
+ # Print project-scoped instincts
+ if project_instincts:
+ print(f"## PROJECT-SCOPED ({project['name']})")
+ print()
+ _print_instincts_by_domain(project_instincts)
+
+ # Print global instincts
+ if global_instincts:
+ print(f"## GLOBAL (apply to all projects)")
+ print()
+ _print_instincts_by_domain(global_instincts)
+
+ # Observations stats
+ obs_file = project.get("observations_file")
+ if obs_file and Path(obs_file).exists():
+ with open(obs_file) as f:
+ obs_count = sum(1 for _ in f)
+ print(f"-" * 60)
+ print(f" Observations: {obs_count} events logged")
+ print(f" File: {obs_file}")
+
+ print(f"\n{'='*60}\n")
+ return 0
+
+
+def _print_instincts_by_domain(instincts: list[dict]) -> None:
+ """Helper to print instincts grouped by domain."""
+ by_domain = defaultdict(list)
+ for inst in instincts:
+ domain = inst.get('domain', 'general')
+ by_domain[domain].append(inst)
+
for domain in sorted(by_domain.keys()):
domain_instincts = by_domain[domain]
- print(f"## {domain.upper()} ({len(domain_instincts)})")
+ print(f" ### {domain.upper()} ({len(domain_instincts)})")
print()
for inst in sorted(domain_instincts, key=lambda x: -x.get('confidence', 0.5)):
conf = inst.get('confidence', 0.5)
- conf_bar = '█' * int(conf * 10) + '░' * (10 - int(conf * 10))
+ conf_bar = '\u2588' * int(conf * 10) + '\u2591' * (10 - int(conf * 10))
trigger = inst.get('trigger', 'unknown trigger')
- source = inst.get('source', 'unknown')
+ scope_tag = f"[{inst.get('scope', '?')}]"
- print(f" {conf_bar} {int(conf*100):3d}% {inst.get('id', 'unnamed')}")
- print(f" trigger: {trigger}")
+ print(f" {conf_bar} {int(conf*100):3d}% {inst.get('id', 'unnamed')} {scope_tag}")
+ print(f" trigger: {trigger}")
# Extract action from content
content = inst.get('content', '')
action_match = re.search(r'## Action\s*\n\s*(.+?)(?:\n\n|\n##|$)', content, re.DOTALL)
if action_match:
action = action_match.group(1).strip().split('\n')[0]
- print(f" action: {action[:60]}{'...' if len(action) > 60 else ''}")
+ print(f" action: {action[:60]}{'...' if len(action) > 60 else ''}")
print()
- # Observations stats
- if OBSERVATIONS_FILE.exists():
- obs_count = sum(1 for _ in open(OBSERVATIONS_FILE))
- print(f"─────────────────────────────────────────────────────────")
- print(f" Observations: {obs_count} events logged")
- print(f" File: {OBSERVATIONS_FILE}")
-
- print(f"\n{'='*60}\n")
-
# ─────────────────────────────────────────────
# Import Command
# ─────────────────────────────────────────────
-def cmd_import(args):
+def cmd_import(args) -> int:
"""Import instincts from file or URL."""
+ project = detect_project()
source = args.source
+ # Determine target scope
+ target_scope = args.scope or "project"
+ if target_scope == "project" and project["id"] == "global":
+ print("No project detected. Importing as global scope.")
+ target_scope = "global"
+
# Fetch content
if source.startswith('http://') or source.startswith('https://'):
print(f"Fetching from URL: {source}")
@@ -192,9 +445,10 @@ def cmd_import(args):
print(f"Error fetching URL: {e}", file=sys.stderr)
return 1
else:
- path = Path(source).expanduser()
- if not path.exists():
- print(f"File not found: {path}", file=sys.stderr)
+ try:
+ path = _validate_file_path(source, must_exist=True)
+ except ValueError as e:
+ print(f"Invalid path: {e}", file=sys.stderr)
return 1
content = path.read_text()
@@ -204,10 +458,14 @@ def cmd_import(args):
print("No valid instincts found in source.")
return 1
- print(f"\nFound {len(new_instincts)} instincts to import.\n")
+ print(f"\nFound {len(new_instincts)} instincts to import.")
+ print(f"Target scope: {target_scope}")
+ if target_scope == "project":
+ print(f"Target project: {project['name']} ({project['id']})")
+ print()
- # Load existing
- existing = load_all_instincts()
+ # Load existing instincts for dedup
+ existing = load_all_instincts(project)
existing_ids = {i.get('id') for i in existing}
# Categorize
@@ -218,7 +476,6 @@ def cmd_import(args):
for inst in new_instincts:
inst_id = inst.get('id')
if inst_id in existing_ids:
- # Check if we should update
existing_inst = next((e for e in existing if e.get('id') == inst_id), None)
if existing_inst:
if inst.get('confidence', 0) > existing_inst.get('confidence', 0):
@@ -229,7 +486,7 @@ def cmd_import(args):
to_add.append(inst)
# Filter by minimum confidence
- min_conf = args.min_confidence or 0.0
+ min_conf = args.min_confidence if args.min_confidence is not None else 0.0
to_add = [i for i in to_add if i.get('confidence', 0.5) >= min_conf]
to_update = [i for i in to_update if i.get('confidence', 0.5) >= min_conf]
@@ -266,13 +523,24 @@ def cmd_import(args):
print("Cancelled.")
return 0
- # Write to inherited directory
+ # Determine output directory based on scope
+ if target_scope == "global":
+ output_dir = GLOBAL_INHERITED_DIR
+ else:
+ output_dir = project["instincts_inherited"]
+
+ output_dir.mkdir(parents=True, exist_ok=True)
+
+ # Write
timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
source_name = Path(source).stem if not source.startswith('http') else 'web-import'
- output_file = INHERITED_DIR / f"{source_name}-{timestamp}.yaml"
+ output_file = output_dir / f"{source_name}-{timestamp}.yaml"
all_to_write = to_add + to_update
- output_content = f"# Imported from {source}\n# Date: {datetime.now().isoformat()}\n\n"
+ output_content = f"# Imported from {source}\n# Date: {datetime.now().isoformat()}\n# Scope: {target_scope}\n"
+ if target_scope == "project":
+ output_content += f"# Project: {project['name']} ({project['id']})\n"
+ output_content += "\n"
for inst in all_to_write:
output_content += "---\n"
@@ -281,7 +549,11 @@ def cmd_import(args):
output_content += f"confidence: {inst.get('confidence', 0.5)}\n"
output_content += f"domain: {inst.get('domain', 'general')}\n"
output_content += f"source: inherited\n"
+ output_content += f"scope: {target_scope}\n"
output_content += f"imported_from: \"{source}\"\n"
+ if target_scope == "project":
+ output_content += f"project_id: {project['id']}\n"
+ output_content += f"project_name: {project['name']}\n"
if inst.get('source_repo'):
output_content += f"source_repo: {inst.get('source_repo')}\n"
output_content += "---\n\n"
@@ -289,7 +561,8 @@ def cmd_import(args):
output_file.write_text(output_content)
- print(f"\n✅ Import complete!")
+ print(f"\nImport complete!")
+ print(f" Scope: {target_scope}")
print(f" Added: {len(to_add)}")
print(f" Updated: {len(to_update)}")
print(f" Saved to: {output_file}")
@@ -301,9 +574,18 @@ def cmd_import(args):
# Export Command
# ─────────────────────────────────────────────
-def cmd_export(args):
+def cmd_export(args) -> int:
"""Export instincts to file."""
- instincts = load_all_instincts()
+ project = detect_project()
+
+ # Determine what to export based on scope filter
+ if args.scope == "project":
+ instincts = load_project_only_instincts(project)
+ elif args.scope == "global":
+ instincts = _load_instincts_from_dir(GLOBAL_PERSONAL_DIR, "personal", "global")
+ instincts += _load_instincts_from_dir(GLOBAL_INHERITED_DIR, "inherited", "global")
+ else:
+ instincts = load_all_instincts(project)
if not instincts:
print("No instincts to export.")
@@ -322,11 +604,17 @@ def cmd_export(args):
return 1
# Generate output
- output = f"# Instincts export\n# Date: {datetime.now().isoformat()}\n# Total: {len(instincts)}\n\n"
+ output = f"# Instincts export\n# Date: {datetime.now().isoformat()}\n# Total: {len(instincts)}\n"
+ if args.scope:
+ output += f"# Scope: {args.scope}\n"
+ if project["id"] != "global":
+ output += f"# Project: {project['name']} ({project['id']})\n"
+ output += "\n"
for inst in instincts:
output += "---\n"
- for key in ['id', 'trigger', 'confidence', 'domain', 'source', 'source_repo']:
+ for key in ['id', 'trigger', 'confidence', 'domain', 'source', 'scope',
+ 'project_id', 'project_name', 'source_repo']:
if inst.get(key):
value = inst[key]
if key == 'trigger':
@@ -338,8 +626,13 @@ def cmd_export(args):
# Write to file or stdout
if args.output:
- Path(args.output).write_text(output)
- print(f"Exported {len(instincts)} instincts to {args.output}")
+ try:
+ out_path = _validate_file_path(args.output)
+ except ValueError as e:
+ print(f"Invalid output path: {e}", file=sys.stderr)
+ return 1
+ out_path.write_text(output)
+ print(f"Exported {len(instincts)} instincts to {out_path}")
else:
print(output)
@@ -350,17 +643,23 @@ def cmd_export(args):
# Evolve Command
# ─────────────────────────────────────────────
-def cmd_evolve(args):
+def cmd_evolve(args) -> int:
"""Analyze instincts and suggest evolutions to skills/commands/agents."""
- instincts = load_all_instincts()
+ project = detect_project()
+ instincts = load_all_instincts(project)
if len(instincts) < 3:
print("Need at least 3 instincts to analyze patterns.")
print(f"Currently have: {len(instincts)}")
return 1
+ project_instincts = [i for i in instincts if i.get('_scope_label') == 'project']
+ global_instincts = [i for i in instincts if i.get('_scope_label') == 'global']
+
print(f"\n{'='*60}")
print(f" EVOLVE ANALYSIS - {len(instincts)} instincts")
+ print(f" Project: {project['name']} ({project['id']})")
+ print(f" Project-scoped: {len(project_instincts)} | Global: {len(global_instincts)}")
print(f"{'='*60}\n")
# Group by domain
@@ -383,7 +682,7 @@ def cmd_evolve(args):
trigger_key = trigger_key.replace(keyword, '').strip()
trigger_clusters[trigger_key].append(inst)
- # Find clusters with 3+ instincts (good skill candidates)
+ # Find clusters with 2+ instincts (good skill candidates)
skill_candidates = []
for trigger, cluster in trigger_clusters.items():
if len(cluster) >= 2:
@@ -392,7 +691,8 @@ def cmd_evolve(args):
'trigger': trigger,
'instincts': cluster,
'avg_confidence': avg_conf,
- 'domains': list(set(i.get('domain', 'general') for i in cluster))
+ 'domains': list(set(i.get('domain', 'general') for i in cluster)),
+ 'scopes': list(set(i.get('scope', 'project') for i in cluster)),
})
# Sort by cluster size and confidence
@@ -403,13 +703,15 @@ def cmd_evolve(args):
if skill_candidates:
print(f"\n## SKILL CANDIDATES\n")
for i, cand in enumerate(skill_candidates[:5], 1):
+ scope_info = ', '.join(cand['scopes'])
print(f"{i}. Cluster: \"{cand['trigger']}\"")
print(f" Instincts: {len(cand['instincts'])}")
print(f" Avg confidence: {cand['avg_confidence']:.0%}")
print(f" Domains: {', '.join(cand['domains'])}")
+ print(f" Scopes: {scope_info}")
print(f" Instincts:")
for inst in cand['instincts'][:3]:
- print(f" - {inst.get('id')}")
+ print(f" - {inst.get('id')} [{inst.get('scope', '?')}]")
print()
# Command candidates (workflow instincts with high confidence)
@@ -418,11 +720,10 @@ def cmd_evolve(args):
print(f"\n## COMMAND CANDIDATES ({len(workflow_instincts)})\n")
for inst in workflow_instincts[:5]:
trigger = inst.get('trigger', 'unknown')
- # Suggest command name
cmd_name = trigger.replace('when ', '').replace('implementing ', '').replace('a ', '')
cmd_name = cmd_name.replace(' ', '-')[:20]
print(f" /{cmd_name}")
- print(f" From: {inst.get('id')}")
+ print(f" From: {inst.get('id')} [{inst.get('scope', '?')}]")
print(f" Confidence: {inst.get('confidence', 0.5):.0%}")
print()
@@ -437,10 +738,14 @@ def cmd_evolve(args):
print(f" Avg confidence: {cand['avg_confidence']:.0%}")
print()
+ # Promotion candidates (project instincts that could be global)
+ _show_promotion_candidates(project)
+
if args.generate:
- generated = _generate_evolved(skill_candidates, workflow_instincts, agent_candidates)
+ evolved_dir = project["evolved_dir"] if project["id"] != "global" else GLOBAL_EVOLVED_DIR
+ generated = _generate_evolved(skill_candidates, workflow_instincts, agent_candidates, evolved_dir)
if generated:
- print(f"\n✅ Generated {len(generated)} evolved structures:")
+ print(f"\nGenerated {len(generated)} evolved structures:")
for path in generated:
print(f" {path}")
else:
@@ -450,11 +755,261 @@ def cmd_evolve(args):
return 0
+# ─────────────────────────────────────────────
+# Promote Command
+# ─────────────────────────────────────────────
+
+def _find_cross_project_instincts() -> dict:
+ """Find instincts that appear in multiple projects (promotion candidates).
+
+ Returns dict mapping instinct ID → list of (project_id, instinct) tuples.
+ """
+ registry = load_registry()
+ cross_project = defaultdict(list)
+
+ for pid, pinfo in registry.items():
+ project_dir = PROJECTS_DIR / pid
+ personal_dir = project_dir / "instincts" / "personal"
+ inherited_dir = project_dir / "instincts" / "inherited"
+
+ for d, stype in [(personal_dir, "personal"), (inherited_dir, "inherited")]:
+ for inst in _load_instincts_from_dir(d, stype, "project"):
+ iid = inst.get('id')
+ if iid:
+ cross_project[iid].append((pid, pinfo.get('name', pid), inst))
+
+ # Filter to only those appearing in 2+ projects
+ return {iid: entries for iid, entries in cross_project.items() if len(entries) >= 2}
+
+
+def _show_promotion_candidates(project: dict) -> None:
+ """Show instincts that could be promoted from project to global."""
+ cross = _find_cross_project_instincts()
+
+ if not cross:
+ return
+
+ # Filter to high-confidence ones not already global
+ global_instincts = _load_instincts_from_dir(GLOBAL_PERSONAL_DIR, "personal", "global")
+ global_instincts += _load_instincts_from_dir(GLOBAL_INHERITED_DIR, "inherited", "global")
+ global_ids = {i.get('id') for i in global_instincts}
+
+ candidates = []
+ for iid, entries in cross.items():
+ if iid in global_ids:
+ continue
+ avg_conf = sum(e[2].get('confidence', 0.5) for e in entries) / len(entries)
+ if avg_conf >= PROMOTE_CONFIDENCE_THRESHOLD:
+ candidates.append({
+ 'id': iid,
+ 'projects': [(pid, pname) for pid, pname, _ in entries],
+ 'avg_confidence': avg_conf,
+ 'sample': entries[0][2],
+ })
+
+ if candidates:
+ print(f"\n## PROMOTION CANDIDATES (project -> global)\n")
+ print(f" These instincts appear in {PROMOTE_MIN_PROJECTS}+ projects with high confidence:\n")
+ for cand in candidates[:10]:
+ proj_names = ', '.join(pname for _, pname in cand['projects'])
+ print(f" * {cand['id']} (avg: {cand['avg_confidence']:.0%})")
+ print(f" Found in: {proj_names}")
+ print()
+ print(f" Run `instinct-cli.py promote` to promote these to global scope.\n")
+
+
+def cmd_promote(args) -> int:
+ """Promote project-scoped instincts to global scope."""
+ project = detect_project()
+
+ if args.instinct_id:
+ # Promote a specific instinct
+ return _promote_specific(project, args.instinct_id, args.force)
+ else:
+ # Auto-detect promotion candidates
+ return _promote_auto(project, args.force, args.dry_run)
+
+
+def _promote_specific(project: dict, instinct_id: str, force: bool) -> int:
+ """Promote a specific instinct by ID from current project to global."""
+ if not _validate_instinct_id(instinct_id):
+ print(f"Invalid instinct ID: '{instinct_id}'.", file=sys.stderr)
+ return 1
+
+ project_instincts = load_project_only_instincts(project)
+ target = next((i for i in project_instincts if i.get('id') == instinct_id), None)
+
+ if not target:
+ print(f"Instinct '{instinct_id}' not found in project {project['name']}.")
+ return 1
+
+ # Check if already global
+ global_instincts = _load_instincts_from_dir(GLOBAL_PERSONAL_DIR, "personal", "global")
+ global_instincts += _load_instincts_from_dir(GLOBAL_INHERITED_DIR, "inherited", "global")
+ if any(i.get('id') == instinct_id for i in global_instincts):
+ print(f"Instinct '{instinct_id}' already exists in global scope.")
+ return 1
+
+ print(f"\nPromoting: {instinct_id}")
+ print(f" From: project '{project['name']}'")
+ print(f" Confidence: {target.get('confidence', 0.5):.0%}")
+ print(f" Domain: {target.get('domain', 'general')}")
+
+ if not force:
+ response = input(f"\nPromote to global? [y/N] ")
+ if response.lower() != 'y':
+ print("Cancelled.")
+ return 0
+
+ # Write to global personal directory
+ output_file = GLOBAL_PERSONAL_DIR / f"{instinct_id}.yaml"
+ output_content = "---\n"
+ output_content += f"id: {target.get('id')}\n"
+ output_content += f"trigger: \"{target.get('trigger', 'unknown')}\"\n"
+ output_content += f"confidence: {target.get('confidence', 0.5)}\n"
+ output_content += f"domain: {target.get('domain', 'general')}\n"
+ output_content += f"source: {target.get('source', 'promoted')}\n"
+ output_content += f"scope: global\n"
+ output_content += f"promoted_from: {project['id']}\n"
+ output_content += f"promoted_date: {datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')}\n"
+ output_content += "---\n\n"
+ output_content += target.get('content', '') + "\n"
+
+ output_file.write_text(output_content)
+ print(f"\nPromoted '{instinct_id}' to global scope.")
+ print(f" Saved to: {output_file}")
+ return 0
+
+
+def _promote_auto(project: dict, force: bool, dry_run: bool) -> int:
+ """Auto-promote instincts found in multiple projects."""
+ cross = _find_cross_project_instincts()
+
+ global_instincts = _load_instincts_from_dir(GLOBAL_PERSONAL_DIR, "personal", "global")
+ global_instincts += _load_instincts_from_dir(GLOBAL_INHERITED_DIR, "inherited", "global")
+ global_ids = {i.get('id') for i in global_instincts}
+
+ candidates = []
+ for iid, entries in cross.items():
+ if iid in global_ids:
+ continue
+ avg_conf = sum(e[2].get('confidence', 0.5) for e in entries) / len(entries)
+ if avg_conf >= PROMOTE_CONFIDENCE_THRESHOLD and len(entries) >= PROMOTE_MIN_PROJECTS:
+ candidates.append({
+ 'id': iid,
+ 'entries': entries,
+ 'avg_confidence': avg_conf,
+ })
+
+ if not candidates:
+ print("No instincts qualify for auto-promotion.")
+ print(f" Criteria: appears in {PROMOTE_MIN_PROJECTS}+ projects, avg confidence >= {PROMOTE_CONFIDENCE_THRESHOLD:.0%}")
+ return 0
+
+ print(f"\n{'='*60}")
+ print(f" AUTO-PROMOTION CANDIDATES - {len(candidates)} found")
+ print(f"{'='*60}\n")
+
+ for cand in candidates:
+ proj_names = ', '.join(pname for _, pname, _ in cand['entries'])
+ print(f" {cand['id']} (avg: {cand['avg_confidence']:.0%})")
+ print(f" Found in {len(cand['entries'])} projects: {proj_names}")
+
+ if dry_run:
+ print(f"\n[DRY RUN] No changes made.")
+ return 0
+
+ if not force:
+ response = input(f"\nPromote {len(candidates)} instincts to global? [y/N] ")
+ if response.lower() != 'y':
+ print("Cancelled.")
+ return 0
+
+ promoted = 0
+ for cand in candidates:
+ if not _validate_instinct_id(cand['id']):
+ print(f"Skipping invalid instinct ID during promotion: {cand['id']}", file=sys.stderr)
+ continue
+
+ # Use the highest-confidence version
+ best_entry = max(cand['entries'], key=lambda e: e[2].get('confidence', 0.5))
+ inst = best_entry[2]
+
+ output_file = GLOBAL_PERSONAL_DIR / f"{cand['id']}.yaml"
+ output_content = "---\n"
+ output_content += f"id: {inst.get('id')}\n"
+ output_content += f"trigger: \"{inst.get('trigger', 'unknown')}\"\n"
+ output_content += f"confidence: {cand['avg_confidence']}\n"
+ output_content += f"domain: {inst.get('domain', 'general')}\n"
+ output_content += f"source: auto-promoted\n"
+ output_content += f"scope: global\n"
+ output_content += f"promoted_date: {datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')}\n"
+ output_content += f"seen_in_projects: {len(cand['entries'])}\n"
+ output_content += "---\n\n"
+ output_content += inst.get('content', '') + "\n"
+
+ output_file.write_text(output_content)
+ promoted += 1
+
+ print(f"\nPromoted {promoted} instincts to global scope.")
+ return 0
+
+
+# ─────────────────────────────────────────────
+# Projects Command
+# ─────────────────────────────────────────────
+
+def cmd_projects(args) -> int:
+ """List all known projects and their instinct counts."""
+ registry = load_registry()
+
+ if not registry:
+ print("No projects registered yet.")
+ print("Projects are auto-detected when you use Claude Code in a git repo.")
+ return 0
+
+ print(f"\n{'='*60}")
+ print(f" KNOWN PROJECTS - {len(registry)} total")
+ print(f"{'='*60}\n")
+
+ for pid, pinfo in sorted(registry.items(), key=lambda x: x[1].get('last_seen', ''), reverse=True):
+ project_dir = PROJECTS_DIR / pid
+ personal_dir = project_dir / "instincts" / "personal"
+ inherited_dir = project_dir / "instincts" / "inherited"
+
+ personal_count = len(_load_instincts_from_dir(personal_dir, "personal", "project"))
+ inherited_count = len(_load_instincts_from_dir(inherited_dir, "inherited", "project"))
+ obs_file = project_dir / "observations.jsonl"
+ if obs_file.exists():
+ with open(obs_file) as f:
+ obs_count = sum(1 for _ in f)
+ else:
+ obs_count = 0
+
+ print(f" {pinfo.get('name', pid)} [{pid}]")
+ print(f" Root: {pinfo.get('root', 'unknown')}")
+ if pinfo.get('remote'):
+ print(f" Remote: {pinfo['remote']}")
+ print(f" Instincts: {personal_count} personal, {inherited_count} inherited")
+ print(f" Observations: {obs_count} events")
+ print(f" Last seen: {pinfo.get('last_seen', 'unknown')}")
+ print()
+
+ # Global stats
+ global_personal = len(_load_instincts_from_dir(GLOBAL_PERSONAL_DIR, "personal", "global"))
+ global_inherited = len(_load_instincts_from_dir(GLOBAL_INHERITED_DIR, "inherited", "global"))
+ print(f" GLOBAL")
+ print(f" Instincts: {global_personal} personal, {global_inherited} inherited")
+
+ print(f"\n{'='*60}\n")
+ return 0
+
+
# ─────────────────────────────────────────────
# Generate Evolved Structures
# ─────────────────────────────────────────────
-def _generate_evolved(skill_candidates: list, workflow_instincts: list, agent_candidates: list) -> list[str]:
+def _generate_evolved(skill_candidates: list, workflow_instincts: list, agent_candidates: list, evolved_dir: Path) -> list[str]:
"""Generate skill/command/agent files from analyzed instinct clusters."""
generated = []
@@ -467,7 +1022,7 @@ def _generate_evolved(skill_candidates: list, workflow_instincts: list, agent_ca
if not name:
continue
- skill_dir = EVOLVED_DIR / "skills" / name
+ skill_dir = evolved_dir / "skills" / name
skill_dir.mkdir(parents=True, exist_ok=True)
content = f"# {name}\n\n"
@@ -493,7 +1048,7 @@ def _generate_evolved(skill_candidates: list, workflow_instincts: list, agent_ca
if not cmd_name:
continue
- cmd_file = EVOLVED_DIR / "commands" / f"{cmd_name}.md"
+ cmd_file = evolved_dir / "commands" / f"{cmd_name}.md"
content = f"# {cmd_name}\n\n"
content += f"Evolved from instinct: {inst.get('id', 'unnamed')}\n"
content += f"Confidence: {inst.get('confidence', 0.5):.0%}\n\n"
@@ -509,7 +1064,7 @@ def _generate_evolved(skill_candidates: list, workflow_instincts: list, agent_ca
if not agent_name:
continue
- agent_file = EVOLVED_DIR / "agents" / f"{agent_name}.md"
+ agent_file = evolved_dir / "agents" / f"{agent_name}.md"
domains = ', '.join(cand['domains'])
instinct_ids = [i.get('id', 'unnamed') for i in cand['instincts']]
@@ -532,12 +1087,13 @@ def _generate_evolved(skill_candidates: list, workflow_instincts: list, agent_ca
# Main
# ─────────────────────────────────────────────
-def main():
- parser = argparse.ArgumentParser(description='Instinct CLI for Continuous Learning v2')
+def main() -> int:
+ _ensure_global_dirs()
+ parser = argparse.ArgumentParser(description='Instinct CLI for Continuous Learning v2.1 (Project-Scoped)')
subparsers = parser.add_subparsers(dest='command', help='Available commands')
# Status
- status_parser = subparsers.add_parser('status', help='Show instinct status')
+ status_parser = subparsers.add_parser('status', help='Show instinct status (project + global)')
# Import
import_parser = subparsers.add_parser('import', help='Import instincts')
@@ -545,17 +1101,30 @@ def main():
import_parser.add_argument('--dry-run', action='store_true', help='Preview without importing')
import_parser.add_argument('--force', action='store_true', help='Skip confirmation')
import_parser.add_argument('--min-confidence', type=float, help='Minimum confidence threshold')
+ import_parser.add_argument('--scope', choices=['project', 'global'], default='project',
+ help='Import scope (default: project)')
# Export
export_parser = subparsers.add_parser('export', help='Export instincts')
export_parser.add_argument('--output', '-o', help='Output file')
export_parser.add_argument('--domain', help='Filter by domain')
export_parser.add_argument('--min-confidence', type=float, help='Minimum confidence')
+ export_parser.add_argument('--scope', choices=['project', 'global', 'all'], default='all',
+ help='Export scope (default: all)')
# Evolve
evolve_parser = subparsers.add_parser('evolve', help='Analyze and evolve instincts')
evolve_parser.add_argument('--generate', action='store_true', help='Generate evolved structures')
+ # Promote (new in v2.1)
+ promote_parser = subparsers.add_parser('promote', help='Promote project instincts to global scope')
+ promote_parser.add_argument('instinct_id', nargs='?', help='Specific instinct ID to promote')
+ promote_parser.add_argument('--force', action='store_true', help='Skip confirmation')
+ promote_parser.add_argument('--dry-run', action='store_true', help='Preview without promoting')
+
+ # Projects (new in v2.1)
+ projects_parser = subparsers.add_parser('projects', help='List known projects and instinct counts')
+
args = parser.parse_args()
if args.command == 'status':
@@ -566,10 +1135,14 @@ def main():
return cmd_export(args)
elif args.command == 'evolve':
return cmd_evolve(args)
+ elif args.command == 'promote':
+ return cmd_promote(args)
+ elif args.command == 'projects':
+ return cmd_projects(args)
else:
parser.print_help()
return 1
if __name__ == '__main__':
- sys.exit(main() or 0)
+ sys.exit(main())
diff --git a/skills/continuous-learning-v2/scripts/test_parse_instinct.py b/skills/continuous-learning-v2/scripts/test_parse_instinct.py
index 10d487e53..41360ebc3 100644
--- a/skills/continuous-learning-v2/scripts/test_parse_instinct.py
+++ b/skills/continuous-learning-v2/scripts/test_parse_instinct.py
@@ -1,7 +1,26 @@
-"""Tests for parse_instinct_file() — verifies content after frontmatter is preserved."""
+"""Tests for continuous-learning-v2 instinct-cli.py
+
+Covers:
+ - parse_instinct_file() — content preservation, edge cases
+ - _validate_file_path() — path traversal blocking
+ - detect_project() — project detection with mocked git/env
+ - load_all_instincts() — loading from project + global dirs, dedup
+ - _load_instincts_from_dir() — directory scanning
+ - cmd_projects() — listing projects from registry
+ - cmd_status() — status display
+ - _promote_specific() — single instinct promotion
+ - _promote_auto() — auto-promotion across projects
+"""
import importlib.util
+import json
import os
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+import pytest
# Load instinct-cli.py (hyphenated filename requires importlib)
_spec = importlib.util.spec_from_file_location(
@@ -10,8 +29,125 @@ _spec = importlib.util.spec_from_file_location(
)
_mod = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(_mod)
+
parse_instinct_file = _mod.parse_instinct_file
+_validate_file_path = _mod._validate_file_path
+detect_project = _mod.detect_project
+load_all_instincts = _mod.load_all_instincts
+load_project_only_instincts = _mod.load_project_only_instincts
+_load_instincts_from_dir = _mod._load_instincts_from_dir
+cmd_status = _mod.cmd_status
+cmd_projects = _mod.cmd_projects
+_promote_specific = _mod._promote_specific
+_promote_auto = _mod._promote_auto
+_find_cross_project_instincts = _mod._find_cross_project_instincts
+load_registry = _mod.load_registry
+_validate_instinct_id = _mod._validate_instinct_id
+_update_registry = _mod._update_registry
+
+
+# ─────────────────────────────────────────────
+# Fixtures
+# ─────────────────────────────────────────────
+
+SAMPLE_INSTINCT_YAML = """\
+---
+id: test-instinct
+trigger: "when writing tests"
+confidence: 0.8
+domain: testing
+scope: project
+---
+
+## Action
+Always write tests first.
+
+## Evidence
+TDD leads to better design.
+"""
+
+SAMPLE_GLOBAL_INSTINCT_YAML = """\
+---
+id: global-instinct
+trigger: "always"
+confidence: 0.9
+domain: security
+scope: global
+---
+
+## Action
+Validate all user input.
+"""
+
+
+def project_tree(tmp_path):
+ """Create a realistic project directory tree for testing."""
+ homunculus = tmp_path / ".claude" / "homunculus"
+ projects_dir = homunculus / "projects"
+ global_personal = homunculus / "instincts" / "personal"
+ global_inherited = homunculus / "instincts" / "inherited"
+ global_evolved = homunculus / "evolved"
+
+ for d in [
+ global_personal, global_inherited,
+ global_evolved / "skills", global_evolved / "commands", global_evolved / "agents",
+ projects_dir,
+ ]:
+ d.mkdir(parents=True, exist_ok=True)
+
+ return {
+ "root": tmp_path,
+ "homunculus": homunculus,
+ "projects_dir": projects_dir,
+ "global_personal": global_personal,
+ "global_inherited": global_inherited,
+ "global_evolved": global_evolved,
+ "registry_file": homunculus / "projects.json",
+ }
+
+
+def patch_globals(project_tree, monkeypatch):
+ """Patch module-level globals to use tmp_path-based directories."""
+ monkeypatch.setattr(_mod, "HOMUNCULUS_DIR", project_tree["homunculus"])
+ monkeypatch.setattr(_mod, "PROJECTS_DIR", project_tree["projects_dir"])
+ monkeypatch.setattr(_mod, "REGISTRY_FILE", project_tree["registry_file"])
+ monkeypatch.setattr(_mod, "GLOBAL_PERSONAL_DIR", project_tree["global_personal"])
+ monkeypatch.setattr(_mod, "GLOBAL_INHERITED_DIR", project_tree["global_inherited"])
+ monkeypatch.setattr(_mod, "GLOBAL_EVOLVED_DIR", project_tree["global_evolved"])
+ monkeypatch.setattr(_mod, "GLOBAL_OBSERVATIONS_FILE", project_tree["homunculus"] / "observations.jsonl")
+ return project_tree
+
+
+def _make_project(tree, pid="abc123", pname="test-project"):
+ """Create project directory structure and return a project dict."""
+ project_dir = tree["projects_dir"] / pid
+ personal_dir = project_dir / "instincts" / "personal"
+ inherited_dir = project_dir / "instincts" / "inherited"
+ for d in [personal_dir, inherited_dir,
+ project_dir / "evolved" / "skills",
+ project_dir / "evolved" / "commands",
+ project_dir / "evolved" / "agents",
+ project_dir / "observations.archive"]:
+ d.mkdir(parents=True, exist_ok=True)
+
+ return {
+ "id": pid,
+ "name": pname,
+ "root": str(tree["root"] / "fake-repo"),
+ "remote": "https://github.com/test/test-project.git",
+ "project_dir": project_dir,
+ "instincts_personal": personal_dir,
+ "instincts_inherited": inherited_dir,
+ "evolved_dir": project_dir / "evolved",
+ "observations_file": project_dir / "observations.jsonl",
+ }
+
+# ─────────────────────────────────────────────
+# parse_instinct_file tests
+# ─────────────────────────────────────────────
MULTI_SECTION = """\
---
@@ -80,3 +216,741 @@ domain: general
result = parse_instinct_file(content)
assert len(result) == 1
assert result[0]["content"] == ""
+
+
+def test_parse_no_id_skipped():
+ """Instincts without an 'id' field should be silently dropped."""
+ content = """\
+---
+trigger: "when doing nothing"
+confidence: 0.5
+---
+
+No id here.
+"""
+ result = parse_instinct_file(content)
+ assert len(result) == 0
+
+
+def test_parse_confidence_is_float():
+ content = """\
+---
+id: float-check
+trigger: "when parsing"
+confidence: 0.42
+domain: general
+---
+
+Body.
+"""
+ result = parse_instinct_file(content)
+ assert isinstance(result[0]["confidence"], float)
+ assert result[0]["confidence"] == pytest.approx(0.42)
+
+
+def test_parse_trigger_strips_quotes():
+ content = """\
+---
+id: quote-check
+trigger: "when quoting"
+confidence: 0.5
+domain: general
+---
+
+Body.
+"""
+ result = parse_instinct_file(content)
+ assert result[0]["trigger"] == "when quoting"
+
+
+def test_parse_empty_string():
+ result = parse_instinct_file("")
+ assert result == []
+
+
+def test_parse_garbage_input():
+ result = parse_instinct_file("this is not yaml at all\nno frontmatter here")
+ assert result == []
+
+
+# ─────────────────────────────────────────────
+# _validate_file_path tests
+# ─────────────────────────────────────────────
+
+def test_validate_normal_path(tmp_path):
+ test_file = tmp_path / "test.yaml"
+ test_file.write_text("hello")
+ result = _validate_file_path(str(test_file), must_exist=True)
+ assert result == test_file.resolve()
+
+
+def test_validate_rejects_etc():
+ with pytest.raises(ValueError, match="system directory"):
+ _validate_file_path("/etc/passwd")
+
+
+def test_validate_rejects_var_log():
+ with pytest.raises(ValueError, match="system directory"):
+ _validate_file_path("/var/log/syslog")
+
+
+def test_validate_rejects_usr():
+ with pytest.raises(ValueError, match="system directory"):
+ _validate_file_path("/usr/local/bin/foo")
+
+
+def test_validate_rejects_proc():
+ with pytest.raises(ValueError, match="system directory"):
+ _validate_file_path("/proc/self/status")
+
+
+def test_validate_must_exist_fails(tmp_path):
+ with pytest.raises(ValueError, match="does not exist"):
+ _validate_file_path(str(tmp_path / "nonexistent.yaml"), must_exist=True)
+
+
+def test_validate_home_expansion(tmp_path):
+ """Tilde expansion should work."""
+ result = _validate_file_path("~/test.yaml")
+ assert str(result).startswith(str(Path.home()))
+
+
+def test_validate_relative_path(tmp_path, monkeypatch):
+ """Relative paths should be resolved."""
+ monkeypatch.chdir(tmp_path)
+ test_file = tmp_path / "rel.yaml"
+ test_file.write_text("content")
+ result = _validate_file_path("rel.yaml", must_exist=True)
+ assert result == test_file.resolve()
+
+
+# ─────────────────────────────────────────────
+# detect_project tests
+# ─────────────────────────────────────────────
+
+def test_detect_project_global_fallback(patch_globals, monkeypatch):
+ """When no git and no env var, should return global project."""
+ monkeypatch.delenv("CLAUDE_PROJECT_DIR", raising=False)
+
+ # Mock subprocess.run to simulate git not available
+ def mock_run(*args, **kwargs):
+ raise FileNotFoundError("git not found")
+
+ monkeypatch.setattr("subprocess.run", mock_run)
+
+ project = detect_project()
+ assert project["id"] == "global"
+ assert project["name"] == "global"
+
+
+def test_detect_project_from_env(patch_globals, monkeypatch, tmp_path):
+ """CLAUDE_PROJECT_DIR env var should be used as project root."""
+ fake_repo = tmp_path / "my-repo"
+ fake_repo.mkdir()
+ monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(fake_repo))
+
+ # Mock git remote to return a URL
+ def mock_run(cmd, **kwargs):
+ if "rev-parse" in cmd:
+ return SimpleNamespace(returncode=0, stdout=str(fake_repo) + "\n", stderr="")
+ if "get-url" in cmd:
+ return SimpleNamespace(returncode=0, stdout="https://github.com/test/my-repo.git\n", stderr="")
+ return SimpleNamespace(returncode=1, stdout="", stderr="")
+
+ monkeypatch.setattr("subprocess.run", mock_run)
+
+ project = detect_project()
+ assert project["id"] != "global"
+ assert project["name"] == "my-repo"
+
+
+def test_detect_project_git_timeout(patch_globals, monkeypatch):
+ """Git timeout should fall through to global."""
+ monkeypatch.delenv("CLAUDE_PROJECT_DIR", raising=False)
+ import subprocess as sp
+
+ def mock_run(cmd, **kwargs):
+ raise sp.TimeoutExpired(cmd, 5)
+
+ monkeypatch.setattr("subprocess.run", mock_run)
+
+ project = detect_project()
+ assert project["id"] == "global"
+
+
+def test_detect_project_creates_directories(patch_globals, monkeypatch, tmp_path):
+ """detect_project should create the project dir structure."""
+ fake_repo = tmp_path / "structured-repo"
+ fake_repo.mkdir()
+ monkeypatch.setenv("CLAUDE_PROJECT_DIR", str(fake_repo))
+
+ def mock_run(cmd, **kwargs):
+ if "rev-parse" in cmd:
+ return SimpleNamespace(returncode=0, stdout=str(fake_repo) + "\n", stderr="")
+ if "get-url" in cmd:
+ return SimpleNamespace(returncode=1, stdout="", stderr="no remote")
+ return SimpleNamespace(returncode=1, stdout="", stderr="")
+
+ monkeypatch.setattr("subprocess.run", mock_run)
+
+ project = detect_project()
+ assert project["instincts_personal"].exists()
+ assert project["instincts_inherited"].exists()
+ assert (project["evolved_dir"] / "skills").exists()
+
+
+# ─────────────────────────────────────────────
+# _load_instincts_from_dir tests
+# ─────────────────────────────────────────────
+
+def test_load_from_empty_dir(tmp_path):
+ result = _load_instincts_from_dir(tmp_path, "personal", "project")
+ assert result == []
+
+
+def test_load_from_nonexistent_dir(tmp_path):
+ result = _load_instincts_from_dir(tmp_path / "does-not-exist", "personal", "project")
+ assert result == []
+
+
+def test_load_annotates_metadata(tmp_path):
+ """Loaded instincts should have _source_file, _source_type, _scope_label."""
+ yaml_file = tmp_path / "test.yaml"
+ yaml_file.write_text(SAMPLE_INSTINCT_YAML)
+
+ result = _load_instincts_from_dir(tmp_path, "personal", "project")
+ assert len(result) == 1
+ assert result[0]["_source_file"] == str(yaml_file)
+ assert result[0]["_source_type"] == "personal"
+ assert result[0]["_scope_label"] == "project"
+
+
+def test_load_defaults_scope_from_label(tmp_path):
+ """If an instinct has no 'scope' in frontmatter, it should default to scope_label."""
+ no_scope_yaml = """\
+---
+id: no-scope
+trigger: "test"
+confidence: 0.5
+domain: general
+---
+
+Body.
+"""
+ (tmp_path / "no-scope.yaml").write_text(no_scope_yaml)
+ result = _load_instincts_from_dir(tmp_path, "inherited", "global")
+ assert result[0]["scope"] == "global"
+
+
+def test_load_preserves_explicit_scope(tmp_path):
+ """If frontmatter has explicit scope, it should be preserved."""
+ yaml_file = tmp_path / "test.yaml"
+ yaml_file.write_text(SAMPLE_INSTINCT_YAML)
+
+ result = _load_instincts_from_dir(tmp_path, "personal", "global")
+ # Frontmatter says scope: project, scope_label is global
+ # The explicit scope should be preserved (not overwritten)
+ assert result[0]["scope"] == "project"
+
+
+def test_load_handles_corrupt_file(tmp_path, capsys):
+ """Corrupt YAML files should be warned about but not crash."""
+ # A file that will cause parse_instinct_file to return empty
+ (tmp_path / "good.yaml").write_text(SAMPLE_INSTINCT_YAML)
+ (tmp_path / "bad.yaml").write_text("not yaml\nno frontmatter")
+
+ result = _load_instincts_from_dir(tmp_path, "personal", "project")
+ # bad.yaml has no valid instincts (no id), so only good.yaml contributes
+ assert len(result) == 1
+ assert result[0]["id"] == "test-instinct"
+
+
+def test_load_supports_yml_extension(tmp_path):
+ yml_file = tmp_path / "test.yml"
+ yml_file.write_text(SAMPLE_INSTINCT_YAML)
+
+ result = _load_instincts_from_dir(tmp_path, "personal", "project")
+ ids = {i["id"] for i in result}
+ assert "test-instinct" in ids
+
+
+def test_load_supports_md_extension(tmp_path):
+ md_file = tmp_path / "legacy-instinct.md"
+ md_file.write_text(SAMPLE_INSTINCT_YAML)
+
+ result = _load_instincts_from_dir(tmp_path, "personal", "project")
+ ids = {i["id"] for i in result}
+ assert "test-instinct" in ids
+
+
+# ─────────────────────────────────────────────
+# load_all_instincts tests
+# ─────────────────────────────────────────────
+
+def test_load_all_project_and_global(patch_globals):
+ """Should load from both project and global directories."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ # Write a project instinct
+ (project["instincts_personal"] / "proj.yaml").write_text(SAMPLE_INSTINCT_YAML)
+ # Write a global instinct
+ (tree["global_personal"] / "glob.yaml").write_text(SAMPLE_GLOBAL_INSTINCT_YAML)
+
+ result = load_all_instincts(project)
+ ids = {i["id"] for i in result}
+ assert "test-instinct" in ids
+ assert "global-instinct" in ids
+
+
+def test_load_all_project_overrides_global(patch_globals):
+ """When project and global have same ID, project wins."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ # Same ID but different confidence
+ proj_yaml = SAMPLE_INSTINCT_YAML.replace("id: test-instinct", "id: shared-id")
+ proj_yaml = proj_yaml.replace("confidence: 0.8", "confidence: 0.9")
+ glob_yaml = SAMPLE_GLOBAL_INSTINCT_YAML.replace("id: global-instinct", "id: shared-id")
+ glob_yaml = glob_yaml.replace("confidence: 0.9", "confidence: 0.3")
+
+ (project["instincts_personal"] / "shared.yaml").write_text(proj_yaml)
+ (tree["global_personal"] / "shared.yaml").write_text(glob_yaml)
+
+ result = load_all_instincts(project)
+ shared = [i for i in result if i["id"] == "shared-id"]
+ assert len(shared) == 1
+ assert shared[0]["_scope_label"] == "project"
+ assert shared[0]["confidence"] == 0.9
+
+
+def test_load_all_global_only(patch_globals):
+ """Global project should only load global instincts."""
+ tree = patch_globals
+ (tree["global_personal"] / "glob.yaml").write_text(SAMPLE_GLOBAL_INSTINCT_YAML)
+
+ global_project = {
+ "id": "global",
+ "name": "global",
+ "root": "",
+ "project_dir": tree["homunculus"],
+ "instincts_personal": tree["global_personal"],
+ "instincts_inherited": tree["global_inherited"],
+ "evolved_dir": tree["global_evolved"],
+ "observations_file": tree["homunculus"] / "observations.jsonl",
+ }
+
+ result = load_all_instincts(global_project)
+ assert len(result) == 1
+ assert result[0]["id"] == "global-instinct"
+
+
+def test_load_project_only_excludes_global(patch_globals):
+ """load_project_only_instincts should NOT include global instincts."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ (project["instincts_personal"] / "proj.yaml").write_text(SAMPLE_INSTINCT_YAML)
+ (tree["global_personal"] / "glob.yaml").write_text(SAMPLE_GLOBAL_INSTINCT_YAML)
+
+ result = load_project_only_instincts(project)
+ ids = {i["id"] for i in result}
+ assert "test-instinct" in ids
+ assert "global-instinct" not in ids
+
+
+def test_load_project_only_global_fallback_loads_global(patch_globals):
+ """Global fallback should return global instincts for project-only queries."""
+ tree = patch_globals
+ (tree["global_personal"] / "glob.yaml").write_text(SAMPLE_GLOBAL_INSTINCT_YAML)
+
+ global_project = {
+ "id": "global",
+ "name": "global",
+ "root": "",
+ "project_dir": tree["homunculus"],
+ "instincts_personal": tree["global_personal"],
+ "instincts_inherited": tree["global_inherited"],
+ "evolved_dir": tree["global_evolved"],
+ "observations_file": tree["homunculus"] / "observations.jsonl",
+ }
+
+ result = load_project_only_instincts(global_project)
+ assert len(result) == 1
+ assert result[0]["id"] == "global-instinct"
+
+
+def test_load_all_empty(patch_globals):
+ """No instincts at all should return empty list."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ result = load_all_instincts(project)
+ assert result == []
+
+
+# ─────────────────────────────────────────────
+# cmd_status tests
+# ─────────────────────────────────────────────
+
+def test_cmd_status_no_instincts(patch_globals, monkeypatch, capsys):
+ """Status with no instincts should print fallback message."""
+ tree = patch_globals
+ project = _make_project(tree)
+ monkeypatch.setattr(_mod, "detect_project", lambda: project)
+
+ args = SimpleNamespace()
+ ret = cmd_status(args)
+ assert ret == 0
+ out = capsys.readouterr().out
+ assert "No instincts found." in out
+
+
+def test_cmd_status_with_instincts(patch_globals, monkeypatch, capsys):
+ """Status should show project and global instinct counts."""
+ tree = patch_globals
+ project = _make_project(tree)
+ monkeypatch.setattr(_mod, "detect_project", lambda: project)
+
+ (project["instincts_personal"] / "proj.yaml").write_text(SAMPLE_INSTINCT_YAML)
+ (tree["global_personal"] / "glob.yaml").write_text(SAMPLE_GLOBAL_INSTINCT_YAML)
+
+ args = SimpleNamespace()
+ ret = cmd_status(args)
+ assert ret == 0
+ out = capsys.readouterr().out
+ assert "INSTINCT STATUS" in out
+ assert "Project instincts: 1" in out
+ assert "Global instincts: 1" in out
+ assert "PROJECT-SCOPED" in out
+ assert "GLOBAL" in out
+
+
+def test_cmd_status_returns_int(patch_globals, monkeypatch):
+ """cmd_status should always return an int."""
+ tree = patch_globals
+ project = _make_project(tree)
+ monkeypatch.setattr(_mod, "detect_project", lambda: project)
+
+ args = SimpleNamespace()
+ ret = cmd_status(args)
+ assert isinstance(ret, int)
+
+
+# ─────────────────────────────────────────────
+# cmd_projects tests
+# ─────────────────────────────────────────────
+
+def test_cmd_projects_empty_registry(patch_globals, capsys):
+ """No projects should print helpful message."""
+ args = SimpleNamespace()
+ ret = cmd_projects(args)
+ assert ret == 0
+ out = capsys.readouterr().out
+ assert "No projects registered yet." in out
+
+
+def test_cmd_projects_with_registry(patch_globals, capsys):
+ """Should list projects from registry."""
+ tree = patch_globals
+
+ # Create a project dir with instincts
+ pid = "test123abc"
+ project = _make_project(tree, pid=pid, pname="my-app")
+ (project["instincts_personal"] / "inst.yaml").write_text(SAMPLE_INSTINCT_YAML)
+
+ # Write registry
+ registry = {
+ pid: {
+ "name": "my-app",
+ "root": "/home/user/my-app",
+ "remote": "https://github.com/user/my-app.git",
+ "last_seen": "2025-01-15T12:00:00Z",
+ }
+ }
+ tree["registry_file"].write_text(json.dumps(registry))
+
+ args = SimpleNamespace()
+ ret = cmd_projects(args)
+ assert ret == 0
+ out = capsys.readouterr().out
+ assert "my-app" in out
+ assert pid in out
+ assert "1 personal" in out
+
+
+# ─────────────────────────────────────────────
+# _promote_specific tests
+# ─────────────────────────────────────────────
+
+def test_promote_specific_not_found(patch_globals, capsys):
+ """Promoting nonexistent instinct should fail."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ ret = _promote_specific(project, "nonexistent", force=True)
+ assert ret == 1
+ out = capsys.readouterr().out
+ assert "not found" in out
+
+
+def test_promote_specific_rejects_invalid_id(patch_globals, capsys):
+ """Path-like instinct IDs should be rejected before file writes."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ ret = _promote_specific(project, "../escape", force=True)
+ assert ret == 1
+ err = capsys.readouterr().err
+ assert "Invalid instinct ID" in err
+
+
+def test_promote_specific_already_global(patch_globals, capsys):
+ """Promoting an instinct that already exists globally should fail."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ # Write same-id instinct in both project and global
+ (project["instincts_personal"] / "shared.yaml").write_text(SAMPLE_INSTINCT_YAML)
+ global_yaml = SAMPLE_INSTINCT_YAML # same id: test-instinct
+ (tree["global_personal"] / "shared.yaml").write_text(global_yaml)
+
+ ret = _promote_specific(project, "test-instinct", force=True)
+ assert ret == 1
+ out = capsys.readouterr().out
+ assert "already exists in global" in out
+
+
+def test_promote_specific_success(patch_globals, capsys):
+ """Promote a project instinct to global with --force."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ (project["instincts_personal"] / "inst.yaml").write_text(SAMPLE_INSTINCT_YAML)
+
+ ret = _promote_specific(project, "test-instinct", force=True)
+ assert ret == 0
+ out = capsys.readouterr().out
+ assert "Promoted" in out
+
+ # Verify file was created in global dir
+ promoted_file = tree["global_personal"] / "test-instinct.yaml"
+ assert promoted_file.exists()
+ content = promoted_file.read_text()
+ assert "scope: global" in content
+ assert "promoted_from: abc123" in content
+
+
+# ─────────────────────────────────────────────
+# _promote_auto tests
+# ─────────────────────────────────────────────
+
+def test_promote_auto_no_candidates(patch_globals, capsys):
+ """Auto-promote with no cross-project instincts should say so."""
+ tree = patch_globals
+ project = _make_project(tree)
+
+ # Empty registry
+ tree["registry_file"].write_text("{}")
+
+ ret = _promote_auto(project, force=True, dry_run=False)
+ assert ret == 0
+ out = capsys.readouterr().out
+ assert "No instincts qualify" in out
+
+
+def test_promote_auto_dry_run(patch_globals, capsys):
+ """Dry run should list candidates but not write files."""
+ tree = patch_globals
+
+ # Create two projects with the same high-confidence instinct
+ p1 = _make_project(tree, pid="proj1", pname="project-one")
+ p2 = _make_project(tree, pid="proj2", pname="project-two")
+
+ high_conf_yaml = """\
+---
+id: cross-project-instinct
+trigger: "when reviewing"
+confidence: 0.95
+domain: security
+scope: project
+---
+
+## Action
+Always review for injection.
+"""
+ (p1["instincts_personal"] / "cross.yaml").write_text(high_conf_yaml)
+ (p2["instincts_personal"] / "cross.yaml").write_text(high_conf_yaml)
+
+ # Write registry
+ registry = {
+ "proj1": {"name": "project-one", "root": "/a", "remote": "", "last_seen": "2025-01-01T00:00:00Z"},
+ "proj2": {"name": "project-two", "root": "/b", "remote": "", "last_seen": "2025-01-01T00:00:00Z"},
+ }
+ tree["registry_file"].write_text(json.dumps(registry))
+
+ project = p1
+ ret = _promote_auto(project, force=True, dry_run=True)
+ assert ret == 0
+ out = capsys.readouterr().out
+ assert "DRY RUN" in out
+ assert "cross-project-instinct" in out
+
+ # Verify no file was created
+ assert not (tree["global_personal"] / "cross-project-instinct.yaml").exists()
+
+
+def test_promote_auto_writes_file(patch_globals, capsys):
+ """Auto-promote with force should write global instinct file."""
+ tree = patch_globals
+
+ p1 = _make_project(tree, pid="proj1", pname="project-one")
+ p2 = _make_project(tree, pid="proj2", pname="project-two")
+
+ high_conf_yaml = """\
+---
+id: universal-pattern
+trigger: "when coding"
+confidence: 0.85
+domain: general
+scope: project
+---
+
+## Action
+Use descriptive variable names.
+"""
+ (p1["instincts_personal"] / "uni.yaml").write_text(high_conf_yaml)
+ (p2["instincts_personal"] / "uni.yaml").write_text(high_conf_yaml)
+
+ registry = {
+ "proj1": {"name": "project-one", "root": "/a", "remote": "", "last_seen": "2025-01-01T00:00:00Z"},
+ "proj2": {"name": "project-two", "root": "/b", "remote": "", "last_seen": "2025-01-01T00:00:00Z"},
+ }
+ tree["registry_file"].write_text(json.dumps(registry))
+
+ ret = _promote_auto(p1, force=True, dry_run=False)
+ assert ret == 0
+
+ promoted = tree["global_personal"] / "universal-pattern.yaml"
+ assert promoted.exists()
+ content = promoted.read_text()
+ assert "scope: global" in content
+ assert "auto-promoted" in content
+
+
+def test_promote_auto_skips_invalid_id(patch_globals, capsys):
+ tree = patch_globals
+
+ p1 = _make_project(tree, pid="proj1", pname="project-one")
+ p2 = _make_project(tree, pid="proj2", pname="project-two")
+
+ bad_id_yaml = """\
+---
+id: ../escape
+trigger: "when coding"
+confidence: 0.9
+domain: general
+scope: project
+---
+
+## Action
+Invalid id should be skipped.
+"""
+ (p1["instincts_personal"] / "bad.yaml").write_text(bad_id_yaml)
+ (p2["instincts_personal"] / "bad.yaml").write_text(bad_id_yaml)
+
+ registry = {
+ "proj1": {"name": "project-one", "root": "/a", "remote": "", "last_seen": "2025-01-01T00:00:00Z"},
+ "proj2": {"name": "project-two", "root": "/b", "remote": "", "last_seen": "2025-01-01T00:00:00Z"},
+ }
+ tree["registry_file"].write_text(json.dumps(registry))
+
+ ret = _promote_auto(p1, force=True, dry_run=False)
+ assert ret == 0
+ err = capsys.readouterr().err
+ assert "Skipping invalid instinct ID" in err
+ assert not (tree["global_personal"] / "../escape.yaml").exists()
+
+
+# ─────────────────────────────────────────────
+# _find_cross_project_instincts tests
+# ─────────────────────────────────────────────
+
+def test_find_cross_project_empty_registry(patch_globals):
+ tree = patch_globals
+ tree["registry_file"].write_text("{}")
+ result = _find_cross_project_instincts()
+ assert result == {}
+
+
+def test_find_cross_project_single_project(patch_globals):
+ """Single project should return nothing (need 2+)."""
+ tree = patch_globals
+ p1 = _make_project(tree, pid="proj1", pname="project-one")
+ (p1["instincts_personal"] / "inst.yaml").write_text(SAMPLE_INSTINCT_YAML)
+
+ registry = {"proj1": {"name": "project-one", "root": "/a", "remote": "", "last_seen": "2025-01-01T00:00:00Z"}}
+ tree["registry_file"].write_text(json.dumps(registry))
+
+ result = _find_cross_project_instincts()
+ assert result == {}
+
+
+def test_find_cross_project_shared_instinct(patch_globals):
+ """Same instinct ID in 2 projects should be found."""
+ tree = patch_globals
+ p1 = _make_project(tree, pid="proj1", pname="project-one")
+ p2 = _make_project(tree, pid="proj2", pname="project-two")
+
+ (p1["instincts_personal"] / "shared.yaml").write_text(SAMPLE_INSTINCT_YAML)
+ (p2["instincts_personal"] / "shared.yaml").write_text(SAMPLE_INSTINCT_YAML)
+
+ registry = {
+ "proj1": {"name": "project-one", "root": "/a", "remote": "", "last_seen": "2025-01-01T00:00:00Z"},
+ "proj2": {"name": "project-two", "root": "/b", "remote": "", "last_seen": "2025-01-01T00:00:00Z"},
+ }
+ tree["registry_file"].write_text(json.dumps(registry))
+
+ result = _find_cross_project_instincts()
+ assert "test-instinct" in result
+ assert len(result["test-instinct"]) == 2
+
+
+# ─────────────────────────────────────────────
+# load_registry tests
+# ─────────────────────────────────────────────
+
+def test_load_registry_missing_file(patch_globals):
+ result = load_registry()
+ assert result == {}
+
+
+def test_load_registry_corrupt_json(patch_globals):
+ tree = patch_globals
+ tree["registry_file"].write_text("not json at all {{{")
+ result = load_registry()
+ assert result == {}
+
+
+def test_load_registry_valid(patch_globals):
+ tree = patch_globals
+ data = {"abc": {"name": "test", "root": "/test"}}
+ tree["registry_file"].write_text(json.dumps(data))
+ result = load_registry()
+ assert result == data
+
+
+def test_validate_instinct_id():
+ assert _validate_instinct_id("good-id_1.0")
+ assert not _validate_instinct_id("../bad")
+ assert not _validate_instinct_id("bad/name")
+ assert not _validate_instinct_id(".hidden")
+
+
+def test_update_registry_atomic_replaces_file(patch_globals):
+ tree = patch_globals
+ _update_registry("abc123", "demo", "/repo", "https://example.com/repo.git")
+ data = json.loads(tree["registry_file"].read_text())
+ assert "abc123" in data
+ leftovers = list(tree["registry_file"].parent.glob(".projects.json.tmp.*"))
+ assert leftovers == []
diff --git a/tests/hooks/hooks.test.js b/tests/hooks/hooks.test.js
index e86633e8a..f4afd036b 100644
--- a/tests/hooks/hooks.test.js
+++ b/tests/hooks/hooks.test.js
@@ -1183,7 +1183,7 @@ async function runTests() {
assert.ok(hooks.hooks.PreCompact, 'Should have PreCompact hooks');
})) passed++; else failed++;
- if (test('all hook commands use node', () => {
+ if (test('all hook commands use node or are skill shell scripts', () => {
const hooksPath = path.join(__dirname, '..', '..', 'hooks', 'hooks.json');
const hooks = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
@@ -1191,9 +1191,14 @@ async function runTests() {
for (const entry of hookArray) {
for (const hook of entry.hooks) {
if (hook.type === 'command') {
+ const isNode = hook.command.startsWith('node');
+ const isSkillScript = hook.command.includes('/skills/') && (
+ /^(bash|sh)\s/.test(hook.command) ||
+ hook.command.startsWith('${CLAUDE_PLUGIN_ROOT}/skills/')
+ );
assert.ok(
- hook.command.startsWith('node'),
- `Hook command should start with 'node': ${hook.command.substring(0, 50)}...`
+ isNode || isSkillScript,
+ `Hook command should start with 'node' or be a skill shell script: ${hook.command.substring(0, 80)}...`
);
}
}