anvil-dev-framework 0.1.6

package/docs/specifications/SPEC-ANV-VRW/component-07-claude-md.md

@@ -0,0 +1,363 @@
+---
+shard_id: SPEC-ANV-VRW/component-07
+parent: SPEC-ANV-VRW
+title: Automated CLAUDE.md Updates
+status: draft
+linear_issue: ANV-147
+priority: P2
+estimated_hours: 3-4
+dependencies:
+  - component-01-verify
+  - component-05-atomic-actions
+---
+
+# Component 7: Automated CLAUDE.md Updates
+
+## Overview
+
+GitHub Action that extracts patterns from commits and updates CLAUDE.md automatically. This keeps project context fresh without manual maintenance.
+
+> Boris Cherny: "GitHub Actions extraction for CLAUDE.md"
+
+---
+
+## Requirements
+
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|-------------|----------|---------------------|
+| REQ-AC-100 | Weekly GitHub Action runs pattern extraction | P1 | Action runs on schedule |
+| REQ-AC-101 | Extracts common patterns from commit messages | P1 | Patterns identified |
+| REQ-AC-102 | Updates CLAUDE.md Project-Learned Patterns section | P1 | Table updated correctly |
+| REQ-AC-103 | Creates PR for human review (no auto-merge) | P0 | PR created, not merged |
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create Pattern Extraction Script
+**File**: `scripts/extract_patterns.py`
+**Estimated**: 1.5 hours
+
+- [ ] Parse commit messages from last week
+- [ ] Identify recurring patterns (prefixes, file types, etc.)
+- [ ] Extract issue references (ANV-XX, etc.)
+- [ ] Categorize by type (fix, feat, refactor)
+- [ ] Output structured JSON
+
+### Task 2: Create CLAUDE.md Updater
+**File**: `scripts/update_claude_md.py`
+**Estimated**: 1 hour
+
+- [ ] Read current CLAUDE.md
+- [ ] Parse Project-Learned Patterns table
+- [ ] Merge new patterns (avoid duplicates)
+- [ ] Update table with dates
+- [ ] Write updated file
+
+### Task 3: Create GitHub Action
+**File**: `.github/workflows/update-claude-md.yml`
+**Estimated**: 1 hour
+
+- [ ] Weekly schedule (Sundays)
+- [ ] Manual trigger option
+- [ ] Run extraction script
+- [ ] Run update script
+- [ ] Create PR with changes
+
+### Task 4: Testing and Validation
+**Estimated**: 0.5 hours
+
+- [ ] Test with sample commit history
+- [ ] Verify PR creation
+- [ ] Ensure no auto-merge
+- [ ] Test manual trigger
+
+---
+
+## GitHub Action
+
+```yaml
+# .github/workflows/update-claude-md.yml
+name: Update CLAUDE.md
+
+on:
+  schedule:
+    - cron: '0 0 * * 0'  # Weekly on Sunday midnight
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  extract-patterns:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for commit analysis
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Extract patterns from recent commits
+        run: |
+          python scripts/extract_patterns.py > patterns.json
+
+      - name: Update CLAUDE.md
+        run: |
+          python scripts/update_claude_md.py patterns.json
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet CLAUDE.md; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create Pull Request
+        if: steps.changes.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v5
+        with:
+          title: "chore: update CLAUDE.md patterns [automated]"
+          body: |
+            ## Automated Pattern Extraction
+
+            This PR updates the Project-Learned Patterns section in CLAUDE.md
+            based on analysis of recent commits.
+
+            **Review carefully before merging.**
+
+            ---
+            *Generated by weekly CLAUDE.md update workflow*
+          branch: auto/claude-md-update
+          labels: automated,documentation
+          commit-message: "chore: update CLAUDE.md patterns"
+```
+
+---
+
+## Pattern Extraction Script
+
+```python
+#!/usr/bin/env python3
+"""
+Extract patterns from recent git commits.
+
+Usage: python scripts/extract_patterns.py > patterns.json
+"""
+
+import subprocess
+import json
+import re
+from collections import Counter
+from datetime import datetime, timedelta
+
+def get_recent_commits(days=7):
+    """Get commits from the last N days."""
+    since = (datetime.now() - timedelta(days=days)).isoformat()
+    result = subprocess.run(
+        ['git', 'log', f'--since={since}', '--pretty=format:%s||%h||%an'],
+        capture_output=True, text=True
+    )
+    commits = []
+    for line in result.stdout.strip().split('\n'):
+        if '||' in line:
+            parts = line.split('||')
+            commits.append({
+                'message': parts[0],
+                'hash': parts[1],
+                'author': parts[2]
+            })
+    return commits
+
+def extract_patterns(commits):
+    """Identify patterns in commit messages."""
+    patterns = []
+
+    # Count commit prefixes
+    prefix_counter = Counter()
+    issue_refs = Counter()
+    file_patterns = Counter()
+
+    for commit in commits:
+        msg = commit['message']
+
+        # Extract conventional commit prefix
+        prefix_match = re.match(r'^(\w+)[\(:]', msg)
+        if prefix_match:
+            prefix_counter[prefix_match.group(1)] += 1
+
+        # Extract issue references
+        issues = re.findall(r'[A-Z]+-\d+', msg)
+        for issue in issues:
+            issue_refs[issue] += 1
+
+        # Extract file/component mentions
+        components = re.findall(r'\(([^)]+)\)', msg)
+        for comp in components:
+            file_patterns[comp] += 1
+
+    # Convert to patterns
+    if prefix_counter:
+        top_prefix = prefix_counter.most_common(1)[0]
+        if top_prefix[1] >= 3:
+            patterns.append({
+                'name': f'{top_prefix[0].title()} Commits',
+                'description': f'Most common commit type ({top_prefix[1]} commits)',
+                'evidence': ', '.join(issue_refs.keys())[:50]
+            })
+
+    for comp, count in file_patterns.most_common(3):
+        if count >= 2:
+            patterns.append({
+                'name': f'{comp} Focus',
+                'description': f'Frequent changes to {comp} ({count} commits)',
+                'evidence': ', '.join(list(issue_refs.keys())[:3])
+            })
+
+    return patterns
+
+def main():
+    commits = get_recent_commits()
+    patterns = extract_patterns(commits)
+    print(json.dumps({
+        'extracted_at': datetime.now().isoformat(),
+        'commit_count': len(commits),
+        'patterns': patterns
+    }, indent=2))
+
+if __name__ == '__main__':
+    main()
+```
+
+---
+
+## CLAUDE.md Updater Script
+
+```python
+#!/usr/bin/env python3
+"""
+Update CLAUDE.md with extracted patterns.
+
+Usage: python scripts/update_claude_md.py patterns.json
+"""
+
+import sys
+import json
+import re
+from datetime import datetime
+
+def read_file(path):
+    with open(path, 'r') as f:
+        return f.read()
+
+def write_file(path, content):
+    with open(path, 'w') as f:
+        f.write(content)
+
+def parse_patterns_table(content):
+    """Extract existing patterns from CLAUDE.md."""
+    pattern = r'\| Pattern \| Evidence \| Added \|\n\|[-|]+\|\n((?:\|[^|]+\|[^|]+\|[^|]+\|\n)*)'
+    match = re.search(pattern, content)
+    if not match:
+        return []
+
+    rows = match.group(1).strip().split('\n')
+    patterns = []
+    for row in rows:
+        cols = [c.strip() for c in row.split('|')[1:-1]]
+        if len(cols) == 3:
+            patterns.append({
+                'name': cols[0],
+                'evidence': cols[1],
+                'added': cols[2]
+            })
+    return patterns
+
+def merge_patterns(existing, new):
+    """Merge new patterns with existing, avoiding duplicates."""
+    names = {p['name'] for p in existing}
+    today = datetime.now().strftime('%Y-%m-%d')
+
+    merged = list(existing)
+    for pattern in new:
+        if pattern['name'] not in names:
+            merged.append({
+                'name': pattern['name'],
+                'evidence': pattern.get('evidence', ''),
+                'added': today
+            })
+
+    return merged
+
+def format_table(patterns):
+    """Format patterns as markdown table."""
+    lines = ['| Pattern | Evidence | Added |', '|---------|----------|-------|']
+    for p in patterns:
+        lines.append(f"| {p['name']} | {p['evidence']} | {p['added']} |")
+    return '\n'.join(lines)
+
+def update_claude_md(patterns_file):
+    with open(patterns_file) as f:
+        new_data = json.load(f)
+
+    content = read_file('CLAUDE.md')
+    existing = parse_patterns_table(content)
+    merged = merge_patterns(existing, new_data.get('patterns', []))
+
+    new_table = format_table(merged)
+
+    # Replace the table in CLAUDE.md
+    pattern = r'(\| Pattern \| Evidence \| Added \|\n\|[-|]+\|\n)((?:\|[^|]+\|[^|]+\|[^|]+\|\n)*)'
+    updated = re.sub(pattern, new_table + '\n', content)
+
+    write_file('CLAUDE.md', updated)
+    print(f"Updated CLAUDE.md with {len(merged)} patterns")
+
+if __name__ == '__main__':
+    if len(sys.argv) != 2:
+        print("Usage: python update_claude_md.py patterns.json")
+        sys.exit(1)
+    update_claude_md(sys.argv[1])
+```
+
+---
+
+## Test Cases
+
+| Test Case | Input | Expected |
+|-----------|-------|----------|
+| Fresh run | No existing patterns | New patterns added |
+| Duplicate patterns | Same pattern name | Not duplicated |
+| No new patterns | Quiet week | No PR created |
+| Manual trigger | workflow_dispatch | Action runs on demand |
+| PR created | Changes detected | PR with `automated` label |
+
+---
+
+## Safety Measures
+
+| Concern | Mitigation |
+|---------|------------|
+| Bad patterns | Human review via PR |
+| Overwriting good content | Merge, don't replace |
+| Spam PRs | Only create if changes exist |
+| Auto-merge risk | No auto-merge, require approval |
+
+---
+
+## Integration Points
+
+- **Trigger**: Weekly schedule or manual
+- **Input**: Git commit history
+- **Output**: Updated CLAUDE.md via PR
+- **Dependencies**: None (standalone workflow)

package/docs/specifications/SPEC-ANV-VRW/index.md

@@ -0,0 +1,182 @@
+---
+spec_id: SPEC-ANV-VRW
+title: Verification Feedback Loops & Ralph Wiggum Mode
+status: draft
+created: 2026-01-04
+updated: 2026-01-04
+linear_issue: ANV-140
+sharded: true
+references:
+  - https://x.com/bcherny/status/2007179832300581177
+  - https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum
+  - docs/boris-cherny-ralph-wiggum-insights.md
+---
+
+# Verification Feedback Loops & Ralph Wiggum Mode
+
+## Executive Summary
+
+This specification implements proven methodologies from Boris Cherny (Claude Code creator) and Geoffrey Huntley's Ralph Wiggum technique to achieve **2-3x quality improvements** through verification feedback loops and enable **long-running unattended execution**.
+
+### Key Outcomes
+- **Verification-first workflow** that catches issues before they compound
+- **Stop hook gates** that prevent premature task completion
+- **Ralph Wiggum mode** for overnight/unattended execution
+- **Atomic action commands** for rapid inner-loop execution
+- **Self-improving CLAUDE.md** via automated pattern extraction
+
+---
+
+## Shards
+
+| Shard | Title | Linear | Status | Priority |
+|-------|-------|--------|--------|----------|
+| [component-01-verify](./component-01-verify.md) | `/verify` Command | ANV-141 | Draft | P0 |
+| [component-02-stop-gate](./component-02-stop-gate.md) | Stop Hook Verification Gate | ANV-142 | Draft | P0 |
+| [component-03-posttooluse](./component-03-posttooluse.md) | PostToolUse Formatting Hook | ANV-143 | Draft | P0 |
+| [component-04-ralph-wiggum](./component-04-ralph-wiggum.md) | Ralph Wiggum Mode | ANV-144/145 | Draft | P1 |
+| [component-05-atomic-actions](./component-05-atomic-actions.md) | Atomic Action Commands | ANV-146 | Draft | P1 |
+| [component-06-verify-subagent](./component-06-verify-subagent.md) | Verification Subagent | ANV-147 | Draft | P2 |
+| [component-07-claude-md](./component-07-claude-md.md) | Automated CLAUDE.md Updates | ANV-147 | Draft | P2 |
+
+---
+
+## Problem Statement
+
+### Current Gaps vs. Best Practices
+
+| Gap | Impact | Boris/Ralph Evidence |
+|-----|--------|---------------------|
+| No verification feedback loop | Errors compound, manual QA required | Boris: "2-3x quality improvement" |
+| No stop hook gating | Claude exits with failing tests | Boris: Non-zero exit blocks stopping |
+| No PostToolUse formatting | Manual formatting, inconsistent code | Boris: Auto-format on every edit |
+| No long-running mode | Requires constant supervision | Geoffrey: 6 repos overnight, $50k→$297 |
+| Scattered atomic actions | Slow inner loops | Boris: `/commit-push-pr` one-liners |
+| Manual CLAUDE.md updates | Stale project context | Boris: GitHub Actions extraction |
+
+---
+
+## Goals
+
+| Goal | Success Metric |
+|------|---------------|
+| Verification-first workflow | All PRs pass CI before human review |
+| Stop hook enforcement | Zero exits with failing tests |
+| Unattended execution | 4+ hour autonomous sessions |
+| Rapid inner loops | Single command for test→commit→push→PR |
+| Self-improving context | CLAUDE.md updated weekly from commits |
+
+---
+
+## Cross-Cutting Concerns
+
+### Configuration Schema
+
+All components share a common configuration in `.claude/settings.yaml`:
+
+```yaml
+verification:
+  enabled: true
+  commands:
+    test: "npm test"
+    lint: "npm run lint"
+    types: "npm run typecheck"
+  max_iterations: 3
+  required_for_completion: true
+
+ralph_wiggum:
+  enabled: false
+  max_iterations: 50
+  commit_on_success: true
+
+formatting:
+  enabled: true
+  timeout_ms: 500
+```
+
+### Shared Dependencies
+
+- All hooks require bash
+- PostToolUse requires formatters (prettier, black, etc.)
+- Ralph Wiggum requires `/verify` component
+
+---
+
+## Dependencies Between Shards
+
+```
+component-01-verify ──┬──> component-02-stop-gate
+                      │
+                      ├──> component-04-ralph-wiggum ──> component-05-atomic-actions
+                      │
+                      └──> component-06-verify-subagent
+
+component-03-posttooluse (independent, can parallel)
+
+component-07-claude-md (requires component-01, component-05)
+```
+
+---
+
+## File Structure
+
+```
+global/
+├── commands/
+│   ├── verify.md           # /verify skill
+│   ├── ralph.md            # /ralph skill
+│   ├── test-and-commit.md  # Atomic action
+│   ├── commit-push-pr.md   # Atomic action
+│   ├── lint-fix.md         # Atomic action
+│   └── force-exit.md       # Override command
+├── hooks/
+│   ├── stop_gate.sh        # Verification stop hook
+│   ├── ralph_stop.sh       # Ralph Wiggum stop hook
+│   └── post_tool_format.sh # PostToolUse formatter
+├── lib/
+│   ├── verification_runner.py
+│   └── verify_iteration.py
+└── agents/
+    └── verify-app.json     # Verification subagent
+
+.github/
+└── workflows/
+    └── update-claude-md.yml
+
+scripts/
+├── extract_patterns.py     # Pattern extraction
+└── update_claude_md.py     # CLAUDE.md updater
+```
+
+---
+
+## Success Metrics
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| PR CI Pass Rate | >95% | GitHub Actions |
+| Verification Iterations | <2 avg | Command logs |
+| Ralph Mode Completion | >80% tasks | Completion promises |
+| Format Violations | 0 post-save | Git diff checks |
+| CLAUDE.md Freshness | <7 days | Last update date |
+
+---
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|------|------------|
+| Stop hook blocks legitimate exits | Provide `/force-exit` override |
+| Ralph mode infinite loops | Max iterations safety (50 default) |
+| Formatter breaks code | Run tests after formatting |
+| Pattern extraction noise | Human review via PR |
+| Performance degradation | Async hooks, time limits |
+
+---
+
+## References
+
+- Boris Cherny's Claude Code Setup: https://x.com/bcherny/status/2007179832300581177
+- Ralph Wiggum Plugin: https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum
+- Research Document: `docs/boris-cherny-ralph-wiggum-insights.md`
+- Claude Code Best Practices: https://docs.anthropic.com/en/docs/claude-code/best-practices