anvil-dev-framework 0.1.7 → 0.1.9

package/README.md

@@ -1,7 +1,7 @@
 ```
      ___    _   ___     _____ _
     /   \  | \ | \ \   / /_ _| |
-   / /_\ \ |  \| |\ \ / / | || |      v0.1.7.0 (alpha)
+   / /_\ \ |  \| |\ \ / / | || |      v0.1.9.0 (alpha)
   / _____ \| |\  | \ V /  | || |___
  /_/     \_\_| \_|  \_/  |___|_____|
 
@@ -10,7 +10,7 @@
    ══════════════════════════════════════════════════════════
 ```
 
-# Anvil Development Framework <sup>v0.1.7.0</sup>
+# Anvil Development Framework <sup>v0.1.9.0</sup>
 
 > **A structured AI development system for solo builders who demand production-quality output.**
 
@@ -18,18 +18,21 @@ Anvil is a comprehensive framework for AI-assisted software development that com
 
 ---
 
-## 📦 Latest Changes in v0.1.7.0
+## 📦 Latest Changes in v0.1.9.0
 
-*Released: 2026-01-15*
+*Released: 2026-01-17*
 
-- **npm Package Distribution** — Anvil now available via `npm install -g anvil-dev-framework`
-  - Also works with Bun: `bun install -g anvil-dev-framework`
-- **Repository Hygiene System** — Detect and clean up stale PRs, orphan branches, and accumulated stashes
-  - New `/cleanup` command with dry-run and force modes
-  - Integrated into `/healthcheck` and `/orient`
-- **Context Checkpoint System Phase 1** — L1/L2/L3 visual indicators for context thresholds
-- **Statusline v2 Fixes** — Per-agent costs, turns-until-compaction, heartbeat system
-- **/sprint and /ready Integration** — Unified work prioritization commands
+- **Ralph Visibility & Notification System** (ANV-298) — Real-time monitoring for autonomous execution
+  - Live terminal watcher (`ralph-watch`) with progress bars and event stream
+  - macOS Notification Center and TTS announcements for milestones
+  - Slack/Discord webhook integrations for team visibility
+  - REST API with SSE for future GUI integration
+  - Toggle notifications: `--enable/--disable {all,macos,tts,slack,discord}`
+- **Token Efficiency Audit Framework** — Complete token consumption tracking and optimization
+  - `/efficiency` command for historical analysis with weekly/monthly reports
+  - `/token-budget` command for session budget management with alerts
+- **CodeRabbit Deep Integration** — Automated code review workflow
+  - Enhanced `.coderabbit.yaml` with pre-merge checks and custom Anvil validations
 
 See [CHANGELOG.md](CHANGELOG.md) for complete history.
 
@@ -155,16 +158,9 @@ npm install -g anvil-dev-framework
 anvil init
 ```
 
-**Option 3: Homebrew (macOS)** *(coming soon)*
+**Option 3: From Source**
 ```bash
-brew tap alexandercahiz/anvil
-brew install anvil
-anvil init
-```
-
-**Option 4: From Source**
-```bash
-git clone https://github.com/alexandercahiz/anvil-dev-framework.git
+git clone https://github.com/AMPMIO/anvil-dev-framework.git
 cd anvil-dev-framework
 ./scripts/install.sh  # Auto-configures PATH
 anvil init
@@ -499,10 +495,27 @@ This remains your **default approach** for all normal development work.
 
 ### Ralph Mode (Special Scenarios Only)
 
-```
+```bash
+# Manual task description
 /ralph start "Migrate all tests from Jest to Vitest" --max-iterations 50
+
+# From Linear issue (recommended) - fetches subtasks automatically
+/ralph start --issue ANV-209
+
+# From Linear project - process all issues in a project
+/ralph start --project "HUD Development"
 ```
 
+**Linear Integration Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--issue` | Linear issue ID to fetch subtasks from (e.g., `ANV-209`) |
+| `--project` | Linear project name to process all issues |
+| `--subtasks` | Filter subtasks (e.g., `ANV-1..ANV-5` or `ANV-1,ANV-3`) |
+| `--include-done` | Include already-completed issues in project mode |
+| `--no-sync` | Disable syncing status back to Linear |
+
 | Good For | Not Good For |
 |----------|--------------|
 | ✅ Large-scale refactoring with clear completion criteria | ❌ Exploratory work (figuring things out) |
@@ -522,6 +535,40 @@ This remains your **default approach** for all normal development work.
 
 **Recommendation**: Start with `--max-iterations 10` to understand costs before running overnight.
 
+### Monitoring Ralph Sessions
+
+Watch Ralph progress in real-time with the visibility tools:
+
+```bash
+# Terminal 1: Run Ralph
+/ralph start --issue ANV-209
+
+# Terminal 2: Watch progress (full display)
+python3 global/tools/ralph-watch
+
+# Or compact single-line mode
+python3 global/tools/ralph-watch --compact
+```
+
+**Notification Options:**
+```bash
+# Toggle notifications
+python3 global/lib/ralph_notifier.py --disable tts   # Mute TTS
+python3 global/lib/ralph_notifier.py --enable macos  # Enable desktop
+
+# Start API server for external monitoring
+python3 global/api/ralph_api.py --port 8765
+```
+
+**Event Types:**
+- `session_started` — Ralph begins work
+- `subtask_complete` — Linear subtask finished
+- `session_complete` — All work done
+- `error_occurred` — Something went wrong
+- `circuit_breaker` — No file changes detected (stuck)
+
+See `global/tools/README.md` for full documentation.
+
 ### Decision Flowchart
 
 ```
@@ -671,6 +718,7 @@ Anvil uses **four-part versioning**: `MILESTONE.MAJOR.MINOR.PATCH`
 ---
 
 ### Future (Post-1.0)
+- [ ] Homebrew CLI distribution (macOS/Linux)
 - [ ] Additional templates (mobile, Rails, Go)
 - [ ] VS Code extension
 - [ ] Dashboard for metrics
@@ -682,6 +730,7 @@ Anvil uses **four-part versioning**: `MILESTONE.MAJOR.MINOR.PATCH`
 
 | Document | Description |
 |----------|-------------|
+| [System Architecture](docs/system-architecture.md) | **OVERVIEW** — How Linear + CodeRabbit + Claude Code + Memory integrate |
 | [Session Workflow](docs/session-workflow.md) | **START HERE** — Daily coding workflow |
 | [Local Issue Tracking](docs/local-issues.md) | File-based issues without Linear |
 | [Sync Guide](docs/sync.md) | Keep projects updated with framework changes |

package/VERSION

@@ -1 +1 @@
-0.1.7.1
+0.1.9.0

package/docs/ANV-263-hook-logging-investigation.md

@@ -0,0 +1,116 @@
+# Investigation: Pre/Post Tool Use Hook Logging Discrepancy
+
+**Issue**: ANV-263
+**Date**: 2026-01-15
+**Status**: Root cause identified
+
+---
+
+## Problem Statement
+
+The healthcheck report from 2026-01-15-1721 flagged:
+> "pre_tool_use entries (2) much lower than post_tool_use (39) suggests potential hook logging inconsistency"
+
+## Investigation Summary
+
+### Initial Observations
+
+| Metric | pre_tool_use.json | post_tool_use.json |
+|--------|-------------------|-------------------|
+| File size | 23KB → grew to larger | 125KB → smaller |
+| Total entries | 42 | 2 |
+| Unique tool_use_ids | 25 | 1 |
+| Duplicate entries | 17 (40%) | 1 (50%) |
+
+The discrepancy reversed direction during investigation - at the time of analysis, pre_tool_use had MORE entries than post_tool_use.
+
+### Root Cause: Duplicate Hook Registration
+
+**Both hooks are registered in TWO locations:**
+
+1. **Global settings** (`~/.claude/settings.json`):
+   ```json
+   "PreToolUse": [{
+     "hooks": [{
+       "command": "uv run .claude/hooks/pre_tool_use.py"
+     }]
+   }]
+   ```
+
+2. **Local settings** (`.claude/settings.local.json`):
+   ```json
+   "PreToolUse": [{
+     "hooks": [{
+       "command": "uv run .claude/hooks/pre_tool_use.py --announce --track-tokens"
+     }]
+   }]
+   ```
+
+**Result**: Every tool invocation triggers the hook TWICE, producing duplicate log entries.
+
+### Evidence
+
+Duplicate tool_use_ids found (each appears exactly 2 times):
+- `toolu_01SLbsZ2Mqn3eP...`
+- `toolu_018xwr4o547Byp...`
+- `toolu_01SrAGnm2mQ7vp...`
+- `toolu_018SeysS4mLJih...`
+- `toolu_01KAMaFWvecFKQ...`
+
+The consistent 2x duplication pattern confirms the dual registration cause.
+
+### Why Counts Varied
+
+The original healthcheck showed pre_tool_use with fewer entries because:
+1. Logs may have been rotated or cleared at different times
+2. Different sessions accumulated different counts
+3. The healthcheck snapshot was taken at a specific moment
+
+## Recommendations
+
+### Option A: Remove Global Registration (Recommended)
+Remove the hook from `~/.claude/settings.json` since local settings are project-specific and include the correct flags.
+
+```bash
+# Edit ~/.claude/settings.json and remove the PreToolUse and PostToolUse entries
+```
+
+### Option B: Add Deduplication Logic
+Add tool_use_id deduplication in the hook itself:
+
+```python
+# Before appending, check if tool_use_id already exists
+if not any(e.get('tool_use_id') == input_data.get('tool_use_id') for e in log_data):
+    log_data.append(input_data)
+```
+
+### Option C: Use File Locking
+If concurrent execution is needed, use proper file locking:
+
+```python
+import fcntl
+with open(log_path, 'r+') as f:
+    fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+    # ... read, modify, write ...
+    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+```
+
+## Related Issues
+
+- ANV-264: Log Rotation (Phase 3b) - will need the log files to be consistent first
+- ANV-260: Parent issue for Insights Recommended Actions
+
+## Files Examined
+
+| File | Purpose |
+|------|---------|
+| `.claude/hooks/pre_tool_use.py` | Pre-tool hook implementation (lines 378-398 for logging) |
+| `.claude/hooks/post_tool_use.py` | Post-tool hook implementation (lines 171-189 for logging) |
+| `.claude/settings.local.json` | Project-specific hook registration |
+| `~/.claude/settings.json` | Global hook registration (duplicate) |
+| `logs/pre_tool_use.json` | Pre-tool log file |
+| `logs/post_tool_use.json` | Post-tool log file |
+
+---
+
+**Next Steps**: Fix the duplicate registration, then proceed to ANV-264 (log rotation).