anvil-dev-framework 0.1.6

package/docs/specifications/PLAN-parallel-tracks-anvil-memory-ccs.md

@@ -0,0 +1,494 @@
+---
+plan_id: PLAN-ANV-PARALLEL
+title: Parallel Tracks - Anvil Memory + CCS + Ralph Integration
+status: draft
+created: 2026-01-07
+tracks: 2
+duration: 4 weeks
+---
+
+# Parallel Tracks Implementation Plan
+
+## Overview
+
+Two parallel work streams that converge at Week 3:
+
+```
+Week 1          Week 2          Week 3          Week 4
+───────────────────────────────────────────────────────────
+TRACK A: Anvil Memory
+[Core DB+CLI] → [Hooks] ──────→ [Integration] → [Polish]
+                                      ↑
+                                      │ MERGE
+                                      ↓
+TRACK B: CCS + Ralph
+[Alerts+UI] ──→ [Handoff Gen] → [Integration] → [Testing]
+───────────────────────────────────────────────────────────
+```
+
+---
+
+## Track A: Anvil Memory System
+
+### A1: Core Database and CLI (Week 1)
+
+**Goal**: Functional CLI with SQLite persistence
+
+#### A1.1: Project Setup
+- [ ] Create `global/tools/anvil-memory/` directory structure
+- [ ] Initialize Bun project (`bun init`)
+- [ ] Configure TypeScript (`tsconfig.json`)
+- [ ] Set up build scripts in `package.json`
+
+**Files to create**:
+```
+global/tools/anvil-memory/
+├── src/
+│   ├── index.ts          # CLI entry point
+│   ├── db.ts             # Database operations
+│   ├── types.ts          # Type definitions
+│   └── commands/
+│       ├── init.ts       # anvil-memory init
+│       ├── observe.ts    # anvil-memory observe
+│       └── search.ts     # anvil-memory search
+├── package.json
+├── tsconfig.json
+└── bunfig.toml
+```
+
+#### A1.2: Database Schema
+- [ ] Create SQLite schema with all tables:
+  - `observations` (main records)
+  - `observations_fts` (full-text search)
+  - `sessions` (conversation boundaries)
+  - `sessions_fts`
+  - `checkpoints` (CCS events)
+  - `ralph_iterations` (Ralph tracking)
+  - `prompts` (user messages)
+  - `prompts_fts`
+- [ ] Implement migration system (version tracking)
+- [ ] Create indexes for common queries
+
+**Acceptance Criteria**:
+- `anvil-memory init` creates `.anvil/memory.db`
+- Schema matches spec exactly
+- FTS5 tables sync via triggers
+
+#### A1.3: Core CLI Commands
+- [ ] `anvil-memory init` - Initialize database
+- [ ] `anvil-memory observe` - Create observation
+- [ ] `anvil-memory search` - Query with FTS5
+- [ ] `anvil-memory get` - Fetch by ID
+
+**Acceptance Criteria**:
+- Commands work from any project directory
+- JSON output for programmatic use
+- Human-readable output for interactive use
+- Error handling with clear messages
+
+#### A1.4: Observation Types
+- [ ] Implement all 10+ observation types
+- [ ] Type validation on create
+- [ ] Concept tag support (array field)
+
+**Observation Types**:
+| Type | Description |
+|------|-------------|
+| bugfix | Bug fixes |
+| feature | New features |
+| refactor | Code restructuring |
+| discovery | Things found |
+| decision | Design choices |
+| change | General changes |
+| checkpoint | CCS checkpoints |
+| ralph_iteration | Ralph loops |
+| handoff | Session continuity |
+| shard | Task breakdown |
+| linear_sync | Issue updates |
+
+---
+
+### A2: Hooks Integration (Week 2)
+
+**Goal**: Claude Code hooks that auto-capture observations
+
+#### A2.1: SessionStart Hook
+- [ ] Create `global/hooks/anvil_memory_session.ts`
+- [ ] Query recent context from database
+- [ ] Format for Claude Code injection
+- [ ] Register in hooks configuration
+
+**Behavior**:
+```typescript
+// Input: Claude Code session start event
+// Output: { additionalContext: "## Recent Context\n..." }
+```
+
+#### A2.2: PostToolUse Hook
+- [ ] Create `global/hooks/anvil_memory_observe.ts`
+- [ ] Analyze tool output for significance
+- [ ] Classify observation type automatically
+- [ ] Create observation in database
+- [ ] Skip low-value tools (TodoWrite, etc.)
+
+**Tools to skip**:
+- TodoWrite
+- AskUserQuestion
+- ListMcpResourcesTool
+- SlashCommand
+- Skill
+
+#### A2.3: Stop Hook
+- [ ] Create `global/hooks/anvil_memory_stop.ts`
+- [ ] Generate session summary
+- [ ] Save to sessions table
+- [ ] Calculate context peak percentage
+
+#### A2.4: Hook Configuration
+- [ ] Add hooks to `.claude/settings.local.json`
+- [ ] Ensure hooks don't conflict with existing
+- [ ] Test hook chain execution order
+
+---
+
+### A3: Context Generation (Week 3 - Merge Point)
+
+**Goal**: Generate useful resume context for sessions
+
+#### A3.1: Recent Context Command
+- [ ] `anvil-memory context` - Generate session context
+- [ ] Progressive disclosure (index first)
+- [ ] Token budget awareness
+- [ ] Format options (inject, markdown, json)
+
+#### A3.2: Timeline Command
+- [ ] `anvil-memory timeline` - Events around anchor
+- [ ] Support depth_before/depth_after
+- [ ] Include all record types interleaved
+
+#### A3.3: Checkpoint Context
+- [ ] Query checkpoints for resume
+- [ ] Include handoff file reference
+- [ ] Format for PROMPT.md injection
+
+---
+
+### A4: Polish and Optimization (Week 4)
+
+#### A4.1: Performance
+- [ ] Query optimization with EXPLAIN
+- [ ] Connection pooling (if needed)
+- [ ] Index tuning based on usage
+
+#### A4.2: Export/Import
+- [ ] `anvil-memory export` - JSON backup
+- [ ] `anvil-memory import` - Restore from backup
+- [ ] Claude-Mem migration (optional)
+
+#### A4.3: Documentation
+- [ ] Usage guide in `docs/guides/anvil-memory.md`
+- [ ] Skill file for Claude Code (`/memory` command)
+- [ ] Integration examples
+
+---
+
+## Track B: Context Checkpoint System + Ralph
+
+### B1: Statusline Alerts and UI (Week 1)
+
+**Goal**: Visual indicators for context thresholds
+
+#### B1.1: Enhance Statusline Hook
+- [ ] Update `global/hooks/statusline.sh` with L1/L2/L3 indicators
+- [ ] Add checkpoint readiness indicator
+- [ ] Show context trend (rising/stable)
+
+**Display format**:
+```
+Before: [CTX: ████████░░ 82%]
+After:  [CTX: ████████░░ 82% ⚠️ L2] [CKPT: Ready]
+```
+
+#### B1.2: Alert Messages
+- [ ] Create alert templates for L1, L2, L3
+- [ ] Implement alert display mechanism
+- [ ] Add suppression for repeated alerts
+
+**Alert Templates**:
+```
+L1 (70%): ⚠️ Context at 70% - Consider completing current task
+L2 (85%): 🔶 Context at 85% - Initiating checkpoint sequence
+L3 (95%): 🔴 Context at 95% - Emergency checkpoint!
+```
+
+#### B1.3: Context Percentage Tracking
+- [ ] Parse context from Claude Code input
+- [ ] Track trend (tokens/minute)
+- [ ] Predict time-to-threshold
+
+---
+
+### B2: Handoff Generation (Week 2)
+
+**Goal**: Automated structured handoff documents
+
+#### B2.1: Handoff Document Generator
+- [ ] Create `global/lib/handoff_generator.py` (or .ts)
+- [ ] Collect session state:
+  - Git status and branch
+  - Modified files
+  - Linear issue state
+  - Current task progress
+- [ ] Generate markdown document
+
+**Handoff Template**:
+```markdown
+---
+checkpoint_trigger: L2 (context at 86%)
+context_at_checkpoint: 86%
+---
+
+# Session Handoff: [Issue] [Title]
+
+## Checkpoint Reason
+[Why checkpoint was triggered]
+
+## Context to Reload
+- CLAUDE.md sections: [list]
+- Active Spec: [path]
+
+## In Progress
+- File: [path] (lines X-Y)
+- Task: [description]
+- Progress: [percentage]
+
+## Git State
+- Branch: [branch]
+- Uncommitted: [yes/no]
+- Modified files: [list]
+
+## Next Steps
+1. [specific action]
+2. [specific action]
+```
+
+#### B2.2: WIP Commit Creation
+- [ ] Create function to generate WIP commit
+- [ ] Commit message format: `[WIP] {issue} - checkpoint (L2 at 85%)`
+- [ ] Only commit if there are changes
+
+#### B2.3: Linear Integration
+- [ ] Update issue with checkpoint comment
+- [ ] Add "context-checkpointed" label (if exists)
+- [ ] Link handoff document in comment
+
+---
+
+### B3: Ralph Integration (Week 2-3)
+
+**Goal**: CCS integrated into Ralph autonomous loop
+
+#### B3.1: Ralph State Enhancement
+- [ ] Add `context_checkpoint` fields to `ralph_state.py`
+- [ ] Track context percentage per iteration
+- [ ] Record checkpoint events
+
+**New fields in RalphState**:
+```python
+@dataclass
+class ContextCheckpoint:
+    active: bool = False
+    level: str = ""  # L1, L2, L3
+    percent_at_checkpoint: int = 0
+    timestamp: str = ""
+    handoff_file: str = ""
+    resume_summary: str = ""
+    files_in_progress: List[Dict] = field(default_factory=list)
+    current_todo_item: str = ""
+    progress_on_item: str = ""
+
+@dataclass
+class RalphState:
+    # ... existing fields ...
+    context_checkpoint: Optional[ContextCheckpoint] = None
+    context_history: List[Dict] = field(default_factory=list)
+```
+
+#### B3.2: Context Monitor Hook
+- [ ] Create `global/hooks/ralph_context_monitor.py`
+- [ ] Monitor context during Ralph iterations
+- [ ] Trigger checkpoint at L2/L3 thresholds
+- [ ] Update ralph-state.json
+
+#### B3.3: Ralph Stop Hook Enhancement
+- [ ] Modify `global/hooks/ralph_stop.sh` to handle checkpoints
+- [ ] Regenerate PROMPT.md with resume context
+- [ ] Decide: continue (exit 1) or stop (exit 0)
+
+**Checkpoint flow in ralph_stop.sh**:
+```bash
+# Check if checkpoint was triggered
+if checkpoint_active; then
+    # Regenerate PROMPT.md with resume context
+    regenerate_prompt_with_resume
+    # Continue loop (fresh context)
+    exit 1
+fi
+```
+
+#### B3.4: PROMPT.md Resume Template
+- [ ] Create template for checkpoint resume
+- [ ] Include Anvil Memory query instructions
+- [ ] Reference handoff document
+
+---
+
+### B4: Integration and Testing (Week 3-4)
+
+**Goal**: Full CCS + Anvil Memory + Ralph integration
+
+#### B4.1: CCS → Anvil Memory Integration
+- [ ] CCS checkpoint → `anvil-memory checkpoint` command
+- [ ] Store checkpoints in Anvil Memory database
+- [ ] Query checkpoints for resume context
+
+#### B4.2: Ralph → Anvil Memory Integration
+- [ ] Ralph iteration → `anvil-memory ralph-iteration` command
+- [ ] Store iteration data in database
+- [ ] Query iteration history for patterns
+
+#### B4.3: End-to-End Testing
+- [ ] Test L1 → L2 → L3 progression
+- [ ] Test checkpoint → resume cycle
+- [ ] Test Ralph overnight run simulation
+- [ ] Test handoff document quality
+
+#### B4.4: Performance Testing
+- [ ] Measure hook latency (<100ms target)
+- [ ] Measure context generation time (<500ms target)
+- [ ] Test with large databases (10k+ observations)
+
+---
+
+## Merge Points and Dependencies
+
+### Week 3 Merge: Integration Point
+
+Track A (Anvil Memory) and Track B (CCS/Ralph) merge when:
+
+| Track A Deliverable | Track B Needs |
+|---------------------|---------------|
+| `anvil-memory checkpoint` | CCS stores checkpoints |
+| `anvil-memory ralph-iteration` | Ralph stores iterations |
+| `anvil-memory context` | Resume context generation |
+| SessionStart hook | Context injection |
+
+### Dependency Graph
+
+```
+A1.1 Project Setup
+  ↓
+A1.2 Database Schema
+  ↓
+A1.3 Core CLI ←──────────────┐
+  ↓                          │
+A2.1-4 Hooks                 │
+  ↓                          │
+A3.1-3 Context Gen ←─────────┼──── B3.4 Resume Template
+                             │
+B1.1-3 Statusline ───────────┤
+  ↓                          │
+B2.1-3 Handoff Gen ──────────┤
+  ↓                          │
+B3.1-4 Ralph Integration ────┘
+  ↓
+B4.1-4 Integration Testing
+```
+
+---
+
+## Task Summary by Track
+
+### Track A: Anvil Memory (Can be worked by Agent 1)
+
+| Week | Tasks | Estimated Effort |
+|------|-------|------------------|
+| 1 | A1.1-A1.4: Core DB + CLI | 3-4 days |
+| 2 | A2.1-A2.4: Hooks | 2-3 days |
+| 3 | A3.1-A3.3: Context Gen | 2-3 days |
+| 4 | A4.1-A4.3: Polish | 2-3 days |
+
+### Track B: CCS + Ralph (Can be worked by Agent 2)
+
+| Week | Tasks | Estimated Effort |
+|------|-------|------------------|
+| 1 | B1.1-B1.3: Statusline | 2-3 days |
+| 2 | B2.1-B2.3: Handoff + B3.1-B3.2: Ralph State | 3-4 days |
+| 3 | B3.3-B3.4: Ralph Integration | 2-3 days |
+| 4 | B4.1-B4.4: Integration Testing | 2-3 days |
+
+---
+
+## Linear Issues to Create
+
+### Track A Issues
+
+| Issue | Title | Priority | Labels |
+|-------|-------|----------|--------|
+| ANV-MEM-1 | Anvil Memory: Project setup and Bun configuration | P0 | feature |
+| ANV-MEM-2 | Anvil Memory: SQLite schema and migrations | P0 | feature |
+| ANV-MEM-3 | Anvil Memory: Core CLI commands (init, observe, search) | P0 | feature |
+| ANV-MEM-4 | Anvil Memory: Observation types and validation | P1 | feature |
+| ANV-MEM-5 | Anvil Memory: SessionStart hook | P0 | feature |
+| ANV-MEM-6 | Anvil Memory: PostToolUse observation hook | P0 | feature |
+| ANV-MEM-7 | Anvil Memory: Stop hook for session summary | P1 | feature |
+| ANV-MEM-8 | Anvil Memory: Context generation command | P0 | feature |
+| ANV-MEM-9 | Anvil Memory: Timeline query command | P1 | feature |
+| ANV-MEM-10 | Anvil Memory: Export/import functionality | P2 | feature |
+
+### Track B Issues
+
+| Issue | Title | Priority | Labels |
+|-------|-------|----------|--------|
+| ANV-CCS-1 | CCS: Statusline L1/L2/L3 threshold indicators | P0 | feature |
+| ANV-CCS-2 | CCS: Alert message templates and display | P1 | feature |
+| ANV-CCS-3 | CCS: Context percentage tracking and trend | P1 | feature |
+| ANV-CCS-4 | CCS: Handoff document generator | P0 | feature |
+| ANV-CCS-5 | CCS: WIP commit creation on checkpoint | P0 | feature |
+| ANV-CCS-6 | CCS: Linear issue checkpoint comments | P1 | feature |
+| ANV-RLP-1 | Ralph: Add context_checkpoint to state | P0 | feature |
+| ANV-RLP-2 | Ralph: Context monitor hook | P0 | feature |
+| ANV-RLP-3 | Ralph: Stop hook checkpoint handling | P0 | feature |
+| ANV-RLP-4 | Ralph: PROMPT.md resume template | P0 | feature |
+| ANV-INT-1 | Integration: CCS → Anvil Memory checkpoint storage | P0 | feature |
+| ANV-INT-2 | Integration: Ralph → Anvil Memory iteration storage | P0 | feature |
+| ANV-INT-3 | Integration: End-to-end testing | P0 | chore |
+
+---
+
+## Coordination Notes
+
+### For Parallel Agents
+
+1. **Track A agent** should NOT modify:
+   - `global/hooks/statusline.sh`
+   - `global/hooks/ralph_stop.sh`
+   - `global/lib/ralph_state.py`
+
+2. **Track B agent** should NOT modify:
+   - `global/tools/anvil-memory/*`
+   - `.anvil/memory.db` schema
+
+3. **Merge coordination at Week 3**:
+   - Both agents sync before integration
+   - Track A provides CLI interface spec
+   - Track B uses CLI to store data
+
+### Git Branching
+
+```
+main
+  ├── feature/anvil-memory-core (Track A)
+  ├── feature/ccs-statusline (Track B)
+  └── feature/integration (Week 3 merge)
+```

package/docs/specifications/SPEC-ANV-VRW/component-01-verify.md

@@ -0,0 +1,208 @@
+---
+shard_id: SPEC-ANV-VRW/component-01
+parent: SPEC-ANV-VRW
+title: Verification Command (/verify)
+status: draft
+linear_issue: ANV-141
+priority: P0
+estimated_hours: 4-6
+dependencies: none
+---
+
+# Component 1: Verification Command (`/verify`)
+
+## Overview
+
+A new slash command that runs verification checks with automatic iteration on failure. This is the **highest-impact** feature from Boris Cherny's methodology.
+
+> Boris Cherny: "Verification is #1... 2-3x quality improvement"
+
+---
+
+## Requirements
+
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|-------------|----------|---------------------|
+| REQ-V-100 | Run configurable verification suite (tests, lint, types) | P0 | All configured commands execute |
+| REQ-V-101 | On failure, re-read failing files and attempt fix | P0 | Failing file paths extracted and read |
+| REQ-V-102 | Maximum 3 automatic fix attempts before escalating | P0 | Counter limits iterations |
+| REQ-V-103 | Track verification state (pass/fail/iterations) | P0 | State persisted across iterations |
+| REQ-V-104 | Integrate with stop hook for exit gating | P1 | Stop hook respects verification state |
+| REQ-V-105 | Support custom verification commands per project | P1 | Config overrides defaults |
+| REQ-V-106 | Report verification results in statusline | P2 | Statusline shows pass/fail |
+
+---
+
+## Behavior Flow
+
+```
+User: /verify
+
+Claude:
+1. Run verification suite:
+   - npm test (or configured test command)
+   - npm run lint
+   - npm run typecheck
+
+2. If ALL pass:
+   ✅ Verification passed (tests: 47, lint: clean, types: clean)
+   [Mark task ready for completion]
+
+3. If ANY fail:
+   ❌ Verification failed - 3 test failures
+
+   Analyzing failures...
+   - src/auth/login.test.ts:45 - Expected 200, got 401
+   - src/auth/login.test.ts:67 - Timeout
+
+   Attempting fix (iteration 1/3)...
+   [Re-read failing files]
+   [Apply targeted fix]
+   [Re-run verification]
+
+4. After 3 failed iterations:
+   ⚠️ Verification failed after 3 attempts
+
+   Remaining issues:
+   - [List of unfixed issues]
+
+   Manual intervention required.
+```
+
+---
+
+## Configuration
+
+```yaml
+# .claude/settings.yaml
+verification:
+  commands:
+    test: "npm test"
+    lint: "npm run lint"
+    types: "npm run typecheck"
+  max_iterations: 3
+  required_for_completion: true
+```
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create Skill File
+**File**: `global/commands/verify.md`
+**Estimated**: 1 hour
+
+- [ ] Define skill frontmatter with metadata
+- [ ] Document execution steps
+- [ ] Add argument parsing (custom commands)
+- [ ] Include anti-patterns section
+- [ ] Add examples
+
+### Task 2: Create Verification Runner
+**File**: `global/lib/verification_runner.py`
+**Estimated**: 2 hours
+
+- [ ] Load config from `.claude/settings.yaml`
+- [ ] Execute test suite with output capture
+- [ ] Execute lint with output parsing
+- [ ] Execute typecheck with error extraction
+- [ ] Return structured results (pass/fail/errors)
+- [ ] Parse file paths and line numbers from errors
+
+### Task 3: Create Iteration Logic
+**File**: `global/lib/verify_iteration.py`
+**Estimated**: 1.5 hours
+
+- [ ] Parse verification failures into structured data
+- [ ] Identify failing files and line numbers
+- [ ] Track iteration count (read/write from state file)
+- [ ] Generate fix context for Claude
+- [ ] Re-run verification after fix attempts
+- [ ] Determine when to escalate
+
+### Task 4: Add Configuration Schema
+**File**: `.claude/settings.yaml` (schema update)
+**Estimated**: 0.5 hours
+
+- [ ] Define verification config schema
+- [ ] Support project-specific command overrides
+- [ ] Add `max_iterations` setting
+- [ ] Add `required_for_completion` flag
+- [ ] Document configuration options
+
+---
+
+## Skill Implementation
+
+```markdown
+# /verify - Verification Feedback Loop
+
+> Run verification suite with automatic iteration on failure.
+
+## Arguments
+- (none) - Run full verification suite
+- `--test-only` - Run tests only
+- `--quick` - Skip type checking (faster)
+
+## Execution Steps
+
+### Step 1: Run Verification Suite
+Execute all configured verification commands:
+- Test suite (npm test / pytest / etc.)
+- Linter (eslint / ruff / etc.)
+- Type checker (tsc / mypy / etc.)
+
+### Step 2: Analyze Results
+If all pass → Report success, allow completion
+If any fail → Parse errors, identify failing files
+
+### Step 3: Iterate on Failures (max 3 times)
+1. Re-read each failing file
+2. Analyze the specific error
+3. Apply targeted fix
+4. Re-run failing command only
+5. Repeat until pass or max iterations
+
+### Step 4: Report Final State
+- Success: List all passing checks with counts
+- Failure: List remaining issues, request manual help
+
+## Anti-Patterns
+- ❌ Making broad changes instead of targeted fixes
+- ❌ Continuing past max iterations
+- ❌ Ignoring failing checks
+- ❌ Changing unrelated code during fix
+```
+
+---
+
+## Test Cases
+
+| Test Case | Input | Expected Output |
+|-----------|-------|-----------------|
+| All pass | Clean codebase | `✅ Verification passed` |
+| Single test failure | 1 failing test | Fix attempted, re-run |
+| Multiple failures | 3 errors | All 3 addressed in order |
+| Max iterations | Unfixable error | Escalate after 3 attempts |
+| Custom commands | Project config | Uses project commands |
+| Missing config | No settings.yaml | Uses sensible defaults |
+
+---
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| Test command not found | Report missing, suggest install |
+| Lint timeout | Skip lint, warn user |
+| Parse failure | Log raw output, continue |
+| Permission denied | Report, suggest `chmod` |
+
+---
+
+## Integration Points
+
+- **Input**: User invokes `/verify`
+- **Output**: Verification state for stop hook
+- **Consumers**: Stop hook gate, Ralph Wiggum mode
+- **State File**: `.claude/verification-state.json`