release: v1.1.2 - Development Preview with v1.2 Phase 1

This is a development preview release showcasing active v1.2 development.

## Stable Features (v1.1.2)

Merged from PR #7:
- Project-local keyword configuration via .claude/keywords.json
- Config hierarchy: project → global → defaults
- Removed ~220 lines of hardcoded keywords

## Experimental Features (v1.2 Phase 1)

⚠️ Usage Tracking System (Preview/Observation Mode):

Core Components:
- scripts/usage_tracker.py: Tracks file usefulness objectively
- scripts/usage-track-stop.py: Post-turn analysis via stop hook
- Router integration: Applies learned keyword weights
- Ralph Loop pattern: Automatic learning after 50 turns

What It Does:
- Tracks which .claude/*.md files are injected vs accessed
- Maps documentation → source code relationships
- Calculates usefulness scores (0.0 to 1.0)
- Learns optimal keyword weights from real usage
- Generates: usage_stats.json, usage_history.jsonl, keyword_weights.json

Current Status:
- Infrastructure: Complete and functional
- Data collection: In progress (~14 turns)
- Learning: Waiting for 50-turn trigger
- Validation: Pending

## v1.2 Architecture (4000+ lines of documentation)

Complete designs for upcoming features:
- V1.2_INTELLIGENCE_ROADMAP.md: 4-phase roadmap
- RALPH_LOOP_INSIGHTS.md: Design philosophy
- Self-maintaining documentation system:
  * Foraging agent (discovers undocumented files)
  * Doc refiner agent (maintains existing docs)
  * Usage-driven intelligence (both query usage tracker)

## Files Added

Scripts:
- scripts/usage_tracker.py (540 lines)
- scripts/usage-track-stop.py
- scripts/add-usage-tracking-hook.py

Documentation:
- .claude/modules/usage-tracker.md (850 lines)
- .claude/modules/foraging-agent.md (900 lines)
- .claude/modules/doc-refiner-agent.md (700 lines)
- .claude/modules/unified-agent-architecture.md (500 lines)
- RALPH_LOOP_INSIGHTS.md (700 lines)
- V1.2_INTELLIGENCE_ROADMAP.md
- V1.2_PHASE1_PROGRESS.md
- INTEGRATION_PROGRESS.md
- SESSION_SUMMARY.md
- RELEASE_NOTES_v1.1.2.md

Configuration:
- .claude/CLAUDE.md (project context)
- .claude/keywords.json (dogfooding v1.2 work)
- .claude/modules/*.md (agent designs)

## Files Modified

- scripts/context-router-v2.py: Usage tracker integration
- CHANGELOG.md: Added v1.1.2 entry
- .gitignore: Exclude generated usage data

## Design Philosophy: Ralph Loop

Iterate → Measure → Learn → Refine → Repeat

Not "design perfect system then implement" but:
- Build foundation → observe real usage → learn from data → iterate

## Next Steps

Users:
- Optional: Install stop hook to experiment
- Use normally for 50+ turns
- System learns automatically
- Monitor .claude/usage_stats.json

Development:
- Continue v1.2 work (generates data organically)
- Validate learning at turn 50
- Build Phase 2-4 features

Timeline: v1.2.0 stable release expected in 8-10 weeks

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Garret Sutherland

.claude/CLAUDE.md

@@ -0,0 +1,217 @@
+# claude-cognitive Development (Project-Local Context)
+
+> **Project**: claude-cognitive v1.2 Intelligence Enhancement
+> **Purpose**: Dogfooding - use claude-cognitive to build claude-cognitive
+> **Status**: v1.1 Production (global ~/.claude/), v1.2 Development (this project)
+
+---
+
+## Current Work
+
+**Phase**: v1.2 Planning + Initial Prototyping
+**Focus**: Ralph Loop integration + Phase 1 (Usage Tracking)
+
+**Recent Activity**:
+- ✅ Created V1.2_INTELLIGENCE_ROADMAP.md (comprehensive plan)
+- ✅ Created RALPH_LOOP_INSIGHTS.md (philosophical foundation)
+- ✅ Integrated Ralph Loop pattern into roadmap
+- 🔄 Setting up project-local .claude/ for dogfooding
+- ⏭️ Next: Prototype usage-tracker.py
+
+---
+
+## Project Structure
+
+```
+claude-cognitive-package/
+├── scripts/                          # v1.1 production scripts (copy to ~/.claude/scripts/)
+│   ├── context-router-v2.py         # [v1.1] Core router (INSTALLED GLOBALLY)
+│   ├── history.py                   # [v1.1] History viewer (INSTALLED GLOBALLY)
+│   ├── pool-*.py                    # [v1.1] Pool coordination (INSTALLED GLOBALLY)
+│   │
+│   ├── usage-tracker.py             # [v1.2] PROTOTYPE - Usage learning
+│   ├── semantic-matcher.py          # [v1.2] PROTOTYPE - Fuzzy matching
+│   ├── predictor.py                 # [v1.2] PROTOTYPE - Sequence learning
+│   └── forage.py                    # [v1.2] PROTOTYPE - Ralph Loop foraging
+│
+├── .claude/                          # PROJECT-LOCAL context (this directory)
+│   ├── CLAUDE.md                    # This file
+│   ├── modules/                     # claude-cognitive components
+│   │   ├── context-router.md        # Router internals
+│   │   ├── pool-coordinator.md      # Pool system
+│   │   ├── usage-tracker.md         # v1.2 usage learning
+│   │   └── foraging-agent.md        # v1.2 Ralph Loop agent
+│   └── integrations/
+│       └── claude-code-hooks.md     # Hook integration points
+│
+├── V1.2_INTELLIGENCE_ROADMAP.md     # Master plan
+├── RALPH_LOOP_INSIGHTS.md           # Philosophy
+├── README.md                        # Public-facing docs
+└── templates/                       # User templates
+```
+
+---
+
+## Keywords (Project-Specific)
+
+**v1.2 Development**:
+- usage, tracking, learning, feedback, ralph, loop, iteration
+- foraging, discovery, autonomous, agent, convergence
+- semantic, embedding, similarity, matching
+- prediction, sequence, pre-loading, anticipatory
+- budget, adaptive, threshold, dynamic
+- circuit-breaker, safeguard, protection
+
+**Core Components** (v1.1):
+- router, context, attention, activation, decay
+- keyword, injection, hot, warm, cold
+- history, pool, coordinator, instance
+
+**Files/Modules**:
+- context-router-v2, usage-tracker, foraging-agent
+- semantic-matcher, predictor, history
+
+---
+
+## When Working On...
+
+### **Usage Tracking (Phase 1)**
+Auto-activates:
+- `.claude/modules/usage-tracker.md`
+- `.claude/modules/context-router.md` (integration points)
+
+### **Foraging Agent (Phase 4)**
+Auto-activates:
+- `.claude/modules/foraging-agent.md`
+- `RALPH_LOOP_INSIGHTS.md`
+- `.claude/modules/usage-tracker.md` (feedback loop)
+
+### **Semantic Matching (Phase 2)**
+Auto-activates:
+- `.claude/modules/semantic-matcher.md`
+- `.claude/modules/context-router.md`
+
+### **Pool System**
+Auto-activates:
+- `.claude/modules/pool-coordinator.md`
+- `.claude/integrations/claude-code-hooks.md`
+
+---
+
+## Development Workflow
+
+### Prototyping (Current Phase)
+
+**1. Create Prototype:**
+```bash
+# Phase 1: Usage tracking
+touch scripts/usage-tracker.py
+# Write prototype with _prototype suffix during development
+```
+
+**2. Test on This Project:**
+```bash
+# Dogfood immediately
+cd /home/garret-sutherland/claude-cognitive-package/
+python scripts/usage-tracker.py --test
+
+# Check if it tracks attention state correctly
+cat .claude/attn_state.json
+```
+
+**3. Measure Impact:**
+```bash
+# Before: Baseline context quality
+# After: Context quality with usage tracking
+# Document results in V1.2_INTELLIGENCE_ROADMAP.md
+```
+
+**4. Integrate:**
+```bash
+# Once validated, integrate into context-router-v2.py
+# Or keep standalone if appropriate
+```
+
+### Testing Strategy
+
+**Test Environments:**
+1. **This project** (claude-cognitive itself) - Primary dogfooding
+2. **Small example project** - Validate zero-config experience
+3. **Large project** (if available) - Validate scalability
+
+**Metrics to Track:**
+- Token savings (% reduction)
+- First-turn context quality (% of needed files available)
+- Wasted context (% of injected files unused)
+- Time to productivity (seconds until first useful action)
+
+---
+
+## Critical Principles
+
+### 1. **Dogfooding is Mandatory**
+- Every v1.2 feature tested on claude-cognitive itself first
+- Attention state visible while developing
+- Use pool coordination for multi-session work
+
+### 2. **Ralph Loop Philosophy**
+- Iteration > perfection
+- Objective feedback required
+- Convergence detection prevents waste
+- Circuit breakers prevent disasters
+
+### 3. **Backwards Compatibility**
+- v1.1 users upgrade seamlessly
+- No breaking changes to core router
+- New features opt-in or auto-enabled safely
+
+### 4. **Quantitative Validation**
+- Every feature needs metrics
+- Measure on 3+ projects before merging
+- Document results in roadmap
+
+---
+
+## Quick Reference
+
+**Main Docs**:
+- `V1.2_INTELLIGENCE_ROADMAP.md` - Master plan
+- `RALPH_LOOP_INSIGHTS.md` - Philosophy
+- `README.md` - Public docs
+- `CHANGELOG.md` - Version history
+
+**Context Docs**:
+- `.claude/modules/context-router.md` - Router internals
+- `.claude/modules/usage-tracker.md` - Usage learning (v1.2)
+- `.claude/modules/foraging-agent.md` - Ralph Loop agent (v1.2)
+- `.claude/modules/pool-coordinator.md` - Pool system
+
+**Global Installation**:
+- `~/.claude/scripts/` - v1.1 production scripts (LIVE)
+- `~/.claude/attention_history.jsonl` - Active history log
+- `~/.claude/attn_state.json` - Current attention scores
+
+---
+
+## Next Steps
+
+**Immediate (Today)**:
+1. Create `.claude/modules/*.md` files for v1.2 components
+2. Start prototyping `usage-tracker.py`
+3. Test on this project (dogfood)
+
+**Short-term (This Week)**:
+1. Complete Phase 1 prototypes (usage tracking + explanations)
+2. Measure impact quantitatively
+3. Document results in roadmap
+
+**Medium-term (Next 2 Weeks)**:
+1. Phase 2: Semantic matching + dynamic budgeting
+2. Integration testing on multiple projects
+3. Community feedback (GitHub discussions)
+
+---
+
+**Working on v1.2?** Check current phase in `V1.2_INTELLIGENCE_ROADMAP.md`
+**Need context?** Mention keywords above to activate relevant modules
+**Testing?** Always dogfood on this project first