anvil-dev-framework 0.1.6

package/global/commands/force-exit.md

@@ -0,0 +1,135 @@
+# /force-exit - Bypass Verification Gate
+
+> Force exit even when verification fails. Use with caution.
+
+## When to Use
+- Known test flakiness that can't be fixed immediately
+- Urgent context compaction needed
+- External dependency causing false failures
+- Explicitly instructed by user to bypass
+
+## When NOT to Use
+- To skip fixing actual bugs
+- To avoid dealing with lint errors
+- As a regular workflow shortcut
+- When you haven't tried to fix the issues
+
+## Arguments
+- `reason` (required) - Explanation for bypassing verification
+
+## Execution Steps
+
+### Step 1: Confirm Bypass
+Before forcing exit, ensure:
+- You've attempted to fix the issues
+- The failures are understood (not unknown errors)
+- User has explicitly approved the bypass
+
+### Step 2: Log the Bypass
+Record the reason in the gate log:
+```
+[timestamp] [WARN] Force exit: <reason>
+```
+
+### Step 3: Set Environment Flag
+```bash
+export ANVIL_FORCE_EXIT=true
+```
+
+### Step 4: Allow Exit
+The stop hook will check this flag and allow exit with a warning.
+
+## Usage Examples
+
+### Flaky Test
+```
+User: /force-exit "Test timeout due to CI slowness, will fix in next session"
+
+Claude: ⚠️ Force exit requested
+   Reason: Test timeout due to CI slowness, will fix in next session
+   Verification gate bypassed.
+```
+
+### External Dependency
+```
+User: /force-exit "API endpoint down, integration test failing"
+
+Claude: ⚠️ Force exit requested
+   Reason: API endpoint down, integration test failing
+   Verification gate bypassed.
+```
+
+### Context Compaction Urgent
+```
+User: /force-exit "Context at 95%, need to compact before losing work"
+
+Claude: ⚠️ Force exit requested
+   Reason: Context at 95%, need to compact before losing work
+   Verification gate bypassed.
+```
+
+## Output Format
+
+### Success (Bypass Granted)
+```
+⚠️ Force exit granted
+
+Reason: [user's reason]
+Bypassing: tests, lint (2 failing checks)
+
+WARNING: Exiting with unresolved verification failures.
+Consider creating a ticket to address these issues.
+```
+
+### Denied (No Reason)
+```
+❌ Force exit requires a reason
+
+Usage: /force-exit "explanation for bypassing"
+
+This helps track why verification was skipped.
+```
+
+## Safety Mechanisms
+
+| Protection | Description |
+|------------|-------------|
+| Reason required | Must explain why bypassing |
+| Logged | All bypasses recorded with timestamp |
+| Warning shown | Clear indication this is non-standard |
+| No auto-bypass | User must explicitly request |
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| ❌ Force exit without trying to fix | ✅ Attempt fixes first |
+| ❌ Use vague reasons ("it's fine") | ✅ Be specific about the issue |
+| ❌ Bypass repeatedly for same issue | ✅ Create a ticket to properly fix |
+| ❌ Force exit to save time | ✅ Fix issues or document why not |
+
+## Logging
+
+All force exits are logged to `.claude/logs/stop_gate.log`:
+
+```
+[2026-01-04T14:30:00Z] [WARN] Force exit requested - bypassing verification gate
+[2026-01-04T14:30:00Z] [WARN] Reason: Test timeout due to CI slowness
+[2026-01-04T14:30:00Z] [WARN] Bypassed checks: tests (1 failure)
+```
+
+## Integration Points
+
+| Component | Integration |
+|-----------|-------------|
+| Stop Hook | Checks ANVIL_FORCE_EXIT flag |
+| /verify | Shows what's being bypassed |
+| Gate Logger | Records bypass event |
+| Handoff | Should mention unresolved issues |
+
+## Key Behaviors
+
+1. **Always require a reason** - No silent bypasses
+2. **Log everything** - Audit trail for bypasses
+3. **Show warnings** - User should know this is non-standard
+4. **Single use** - Flag resets after exit, not persistent

package/global/commands/handoff.md

@@ -0,0 +1,191 @@
+# /handoff - Generate Session Continuity Document
+
+> Create a handoff document preserving context for the next session.
+
+## When to Use
+- At the end of every session
+- Before stepping away for extended time
+- When switching between tasks
+- Before context compaction
+
+## Execution Steps
+
+### Step 1: Gather Session Context
+
+Collect:
+- Current branch and git status
+- Issues worked on this session
+- Files modified
+- Current time/date
+
+### Step 2: Document Completed Work
+List what was accomplished:
+- Issues moved to "Done" or "In Review"
+- PRs created
+- Key decisions made
+
+### Step 3: Document In-Progress State
+For any incomplete work:
+- Current state of implementation
+- What's left to do
+- Any blockers encountered
+- Files that were being edited
+
+### Step 4: Document Discovered Work
+List any new issues/tasks discovered:
+- Reference `/discover` calls made
+- Captured in Linear or not yet filed
+
+### Step 5: Capture Environment State
+```bash
+git status
+git diff --stat
+git log --oneline -3
+```
+
+### Step 5.5: Verify Changelog Entry
+
+Before finalizing handoff, check if user-facing work was done this session:
+
+1. If work was user-facing (features, fixes, changes), verify CHANGELOG.md was updated:
+   ```bash
+   git diff --name-only main...HEAD | grep -c "CHANGELOG.md" || echo "0"
+   ```
+
+2. If no changelog entry detected but user-facing work completed:
+   ```markdown
+   ⚠️ Changelog Reminder:
+   You completed work this session but no CHANGELOG.md entry was detected.
+
+   Should this work be documented in the changelog?
+   - If yes: Add entry to [Unreleased] section before completing handoff
+   - If no: Internal/infrastructure change, proceed without entry
+   ```
+
+3. Document status for handoff:
+   - **Entry added**: Note what was added to [Unreleased]
+   - **No entry needed**: Confirm internal-only changes
+   - **Deferred**: Note that entry is still needed (carry forward to next session)
+
+**Note**: This is a soft prompt—use judgment. Internal refactors and test-only changes don't require changelog entries.
+
+---
+
+### Step 6: Write Handoff File
+
+Create file at: `.claude/handoffs/YYYY-MM-DD-HHMM.md`
+
+Template:
+```markdown
+---
+session_date: YYYY-MM-DD
+session_time: HH:MM
+branch: [current branch]
+linear_issues: [comma-separated issue keys]
+---
+
+# Session Handoff: [Brief description]
+
+## Session Summary
+[1-2 sentence summary of what this session was about]
+
+## Completed This Session
+- [x] [Issue key]: [What was done]
+- [x] [Description of completed work]
+
+## In Progress (Not Complete)
+### [Issue key]: [Title]
+- **Current state**: [Where we left off]
+- **Next steps**: [What needs to happen next]
+- **Files touched**: [List key files]
+- **Blockers**: [Any blockers]
+
+## Discovered Work
+- [ ] [Description] → Filed as [Issue key] / Not yet filed
+- [ ] [Description] → Filed as [Issue key] / Not yet filed
+
+## Environment State
+- **Branch**: [branch name]
+- **Uncommitted changes**: [yes/no, brief description]
+- **Last commit**: [hash] [message]
+
+## Changelog Status
+- **Entry added to [Unreleased]**: Yes / No / Deferred
+- **Change type**: Added / Changed / Fixed / Removed / N/A
+- **Entry preview**: [First line of changelog entry, or "Internal changes only"]
+
+## Recommended Next Task
+[What should be tackled first next session and why]
+
+## Critical Context for Next Session
+[Any important context that might be lost]
+- [Key decision made and why]
+- [Important constraint discovered]
+- [Thing to remember]
+```
+
+### Step 7: Deregister Agent (If Registered)
+
+If agent registration is enabled (multi-terminal coordination), deregister this session:
+
+```bash
+# Deregister agent with session summary
+python3 project/hooks/session_start.py --deregister-agent --summary "[brief summary of work done]"
+```
+
+This:
+- Removes agent from coordination.md Active Sessions
+- Adds completion entry to Session Log
+- Clears agent from anvil-state.json
+
+**Note**: Skip if not using multi-terminal coordination.
+
+### Step 8: Confirm Handoff
+
+Output:
+```
+## Handoff Created
+
+**File**: .claude/handoffs/YYYY-MM-DD-HHMM.md
+**Session duration**: ~X hours
+**Work items**: Y completed, Z in progress
+**Agent**: [agent-id] deregistered (if applicable)
+
+Next session should start with `/orient` to pick up context.
+```
+
+## Key Behaviors
+- Be thorough—context is expensive to reconstruct
+- Include specific file paths and line numbers
+- Capture the "why" not just the "what"
+- Recommend specific next action
+- Verify changelog entry for user-facing work before handoff
+
+## State Sync (ANV-176)
+
+After creating the handoff document, update the session state:
+
+```bash
+python3 global/lib/state_manager.py handoff
+```
+
+This updates `.claude/anvil-state.json` with:
+- `phase: "handoff"`
+- Sets `lastCommand: "/handoff"`
+
+And syncs to the agent registry for statusline visibility.
+
+## Linear Issue State Note
+
+If you created and merged a PR during this session, the associated Linear issue has **already been moved to Done** by Linear's GitHub integration. You don't need to manually update its status.
+
+Check issue state before attempting updates — the `linear.py` state guard will skip redundant updates automatically.
+
+## Integration Points
+- Creates: `.claude/handoffs/YYYY-MM-DD-HHMM.md`
+- References: Linear issues worked on
+- Used by: `/orient` command next session
+- Calls: `project/hooks/session_start.py --deregister-agent` (if multi-terminal coordination enabled)
+- Updates: `.claude/coordination.md` (removes from Active Sessions, adds to Session Log)
+- Updates: `.claude/anvil-state.json` via state_manager.py
+- Note: Linear issues may have auto-updated on PR merge

package/global/commands/healthcheck.md

@@ -0,0 +1,302 @@
+# /healthcheck - Framework Diagnostics
+
+> Analyze session logs to identify framework issues, hook failures, and edge cases.
+
+## When to Use
+- At end of development session (manual or auto-triggered)
+- After encountering unexpected behavior
+- When hooks seem to not be firing correctly
+- To audit framework health periodically
+
+## Execution Steps
+
+### Step 1: Gather Session Data
+
+Collect data from the current session's logs:
+
+```bash
+# Check log files exist
+ls -la logs/
+
+# Expected files:
+# - pre_tool_use.json    (tool invocations, blocked commands)
+# - post_tool_use.json   (tool responses, errors)
+# - session_start.json   (session metadata)
+# - stop.json            (session end events)
+# - user_prompt_submit.json (command usage)
+```
+
+### Step 2: Analyze Blocked Commands
+
+Search `logs/pre_tool_use.json` for blocked operations:
+
+**Pattern**: Look for entries where safety hooks blocked execution
+- `rm -rf` commands blocked
+- `.env` file access blocked
+- Other safety rule triggers
+
+```python
+# Pseudo-pattern for detection
+blocked = [e for e in pre_tool_use if "BLOCKED" in stderr or exit_code == 2]
+```
+
+### Step 3: Analyze Tool Errors
+
+Search `logs/post_tool_use.json` for failed tool calls:
+
+**Patterns to detect**:
+- `tool_response` containing `error` field
+- File not found errors
+- Permission denied
+- Command execution failures
+- Timeout errors
+
+Group errors by:
+- Tool name (Bash, Read, Write, Glob, etc.)
+- Error type
+- Frequency
+
+### Step 4: Analyze Hook Status
+
+Check hook execution patterns:
+
+| Hook | Expected | Check |
+|------|----------|-------|
+| session_start | 1 per session | Count in session_start.json |
+| pre_tool_use | 1 per tool call | Count matches tool invocations |
+| post_tool_use | 1 per tool call | Count matches tool completions |
+| stop | 1 per session | Present in stop.json |
+
+**Failure indicators**:
+- Missing hook logs when hooks should fire
+- Mismatched counts between pre/post
+- Error messages in hook stderr
+
+### Step 5: Calculate Metrics
+
+Compute session health metrics:
+
+| Metric | Calculation |
+|--------|-------------|
+| Tool Invocations | Count of pre_tool_use entries |
+| Success Rate | (total - errors) / total * 100 |
+| Blocked Commands | Count of BLOCKED entries |
+| Hook Coverage | hooks_fired / expected_hooks |
+
+### Step 6: Check Repository Hygiene (ANV-237)
+
+Run the hygiene service to check for accumulated cruft:
+
+```bash
+python3 global/lib/hygiene_service.py --check --json
+```
+
+The hygiene service checks for:
+- **Stash accumulation**: Warn if stashes exceed threshold (default: 5)
+- **Old stashes**: Flag stashes older than threshold (default: 7 days)
+- **Orphan branches**: Local branches with deleted remote tracking branches
+- **Stale PRs**: Open PRs for issues already marked Done in Linear
+- **Conflict PRs**: Open PRs with merge conflicts
+
+**Status thresholds**:
+
+| Check | ✅ PASS | ⚠️ WARN | ❌ FAIL |
+|-------|---------|---------|---------|
+| Stashes | ≤ threshold | > threshold | — |
+| Old stashes | 0 | 1-3 | > 3 |
+| Orphan branches | 0 | — | > 0 |
+| Stale PRs | 0 | — | > 0 |
+| Conflict PRs | 0 | > 0 | — |
+
+If hygiene issues found, include in recommendations: "Run `/cleanup` to address repository hygiene issues."
+
+### Step 7: Generate Recommendations
+
+Based on findings, generate actionable recommendations:
+
+**If blocked commands > 0**:
+- Review if blocks were false positives
+- Consider adjusting safety rules if legitimate commands blocked
+
+**If tool errors > 3**:
+- Investigate repeated error patterns
+- Check for path issues, permission problems
+
+**If hook failures detected**:
+- Verify hook scripts are executable
+- Check for syntax errors in hook code
+- Verify uv/Python availability
+
+**If hygiene issues found**:
+- Run `/cleanup` to address stale stashes, orphan branches, or stale PRs
+- Consider closing PRs for issues already marked Done
+- Delete local branches with deleted remotes
+
+### Step 8: Create Healthcheck Report
+
+Save to: `.claude/healthchecks/YYYY-MM/{date}-{time}-{slug}.md`
+
+```markdown
+# Healthcheck: YYYY-MM-DD HH:MM
+
+**Session ID**: [from logs]
+**Duration**: [calculated or estimated]
+**Status**: ✅ Healthy | ⚠️ Issues Detected | ❌ Problems Found
+
+## Session Summary
+
+[1-2 sentence narrative of what happened this session]
+
+## Metrics
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Tool Invocations | X | — |
+| Success Rate | X% | ✅/⚠️/❌ |
+| Blocked Commands | X | ✅/⚠️ |
+| Hook Failures | X | ✅/❌ |
+
+## Blocked Commands
+
+| Time | Tool | Input | Reason |
+|------|------|-------|--------|
+| HH:MM | Bash | `rm -rf /` | Dangerous command |
+
+*Or: "No commands blocked this session."*
+
+## Tool Errors
+
+| Tool | Error | Count | Example |
+|------|-------|-------|---------|
+| Glob | File not found | 3 | Pattern `*.xyz` |
+
+*Or: "No tool errors this session."*
+
+## Hook Status
+
+| Hook | Executions | Status |
+|------|------------|--------|
+| session_start | 1 | ✅ |
+| pre_tool_use | 145 | ✅ |
+| post_tool_use | 143 | ✅ |
+| stop | 0 | ⏳ Pending |
+
+## Repository Hygiene
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Stashes | ✅/⚠️ | X total (threshold: Y) |
+| Old stashes | ✅/⚠️/❌ | X stashes older than Y days |
+| Orphan branches | ✅/❌ | X with gone remotes |
+| Stale PRs | ✅/❌ | X for Done issues |
+| Conflict PRs | ✅/⚠️ | X with conflicts |
+
+*Or if all pass: "Repository hygiene: ✅ No issues detected"*
+
+*If issues found: "Run `/cleanup` to address hygiene issues."*
+
+## Recommendations
+
+1. **[Category]**: [Specific recommendation]
+2. **[Category]**: [Specific recommendation]
+
+*Or: "Framework operating normally. No action required."*
+
+## Discovered Work
+
+- [ ] [Issue description] — File with `/discover`
+- [ ] [Issue description] — File with `/discover`
+
+*Or: "No issues discovered."*
+```
+
+### Step 9: Offer to File Issues
+
+If significant issues found:
+
+```
+## Issues Found
+
+The following issues should be filed:
+
+1. **[Title]**: [Description]
+   → Run `/discover` to file as Linear issue
+
+Would you like me to file these now?
+```
+
+### Step 10: Confirm Healthcheck
+
+```
+## Healthcheck Complete
+
+**File**: .claude/healthchecks/2024-12/2024-12-24-1730-session.md
+**Status**: ⚠️ Issues Detected
+**Key Finding**: 3 Glob errors suggest path configuration issue
+
+Run `/insights` to see patterns across multiple healthchecks.
+```
+
+## Log File Reference
+
+### pre_tool_use.json
+```json
+{
+  "session_id": "abc123",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": { "command": "rm -rf /" }
+}
+```
+
+### post_tool_use.json
+```json
+{
+  "session_id": "abc123",
+  "hook_event_name": "PostToolUse",
+  "tool_name": "Glob",
+  "tool_input": { "pattern": "**/*.xyz" },
+  "tool_response": {
+    "filenames": [],
+    "error": "No files found"
+  }
+}
+```
+
+## Status Thresholds
+
+| Metric | ✅ Healthy | ⚠️ Warning | ❌ Problem |
+|--------|-----------|-----------|-----------|
+| Success Rate | >95% | 80-95% | <80% |
+| Blocked Commands | 0-1 | 2-5 | >5 |
+| Hook Failures | 0 | 1-2 | >2 |
+| Tool Errors | 0-3 | 4-10 | >10 |
+| Stash Count | ≤5 | >5 | — |
+| Old Stashes | 0 | 1-3 | >3 |
+| Orphan Branches | 0 | — | >0 |
+| Stale PRs | 0 | — | >0 |
+| Conflict PRs | 0 | >0 | — |
+
+## Key Behaviors
+
+- Analyze current session only (not historical)
+- Be specific about errors (include examples)
+- Recommend actions, not just report issues
+- Offer to file discovered work
+- Keep narrative concise
+
+## What This Command Does NOT Do
+
+- Modify log files
+- Auto-fix issues
+- Analyze historical sessions (use `/insights` for patterns)
+- Replace manual debugging
+
+## Integration Points
+
+- Creates: `.claude/healthchecks/YYYY-MM/*.md`
+- Synthesized by: `/insights` command
+- Triggered by: Stop hook (if `autoHealthcheck` enabled)
+- Files work via: `/discover` command
+- Uses: `global/lib/hygiene_service.py` for repository hygiene checks (ANV-237)
+- Recommends: `/cleanup` command when hygiene issues found

package/global/commands/hud.md

@@ -0,0 +1,84 @@
+# /hud - Launch Multi-Agent Dashboard
+
+> Open the Anvil HUD terminal dashboard for monitoring all active Claude Code agents.
+
+## When to Use
+- **Multi-agent sessions**: Running 2+ Claude Code agents in parallel
+- **Cost monitoring**: Track API spending across agents
+- **Context health**: Watch for compaction warnings
+- **Coordination**: See which files/issues each agent is working on
+
+## Quick Launch
+
+### Option 1: Split Terminal (Recommended)
+Open a new terminal pane (Cmd+D in Warp/iTerm, or `tmux split-window`) and run:
+
+```bash
+uv run global/tools/anvil-hud.py
+```
+
+### Option 2: Demo Mode
+Test the HUD with sample data:
+
+```bash
+uv run global/tools/anvil-hud.py --demo
+```
+
+## Dashboard Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit HUD |
+| `r` | Force refresh |
+| `d` | Toggle detailed view |
+| `?` | Show help |
+
+## What the HUD Shows
+
+### Agent Panel
+- **Agent ID**: Human-readable name (e.g., `swift-falcon-a3f2`)
+- **Model**: Current model (Opus/Sonnet/Haiku)
+- **Context**: Usage percentage with color-coded warnings
+- **Cost**: Session spend in USD
+- **Project**: Working directory
+- **Status**: Active, idle, or stale
+
+### Status Indicators
+| Icon | Meaning |
+|------|---------|
+| ● | Active (recent activity) |
+| ○ | Idle (no recent activity) |
+| ⚠ | Context warning (>70%) |
+| 🔴 | Context critical (>85%) |
+
+## Data Sources
+
+The HUD reads from:
+- `~/.anvil/agents.json` - Agent registry (auto-updated by statusline hook)
+- `.claude/anvil-state.json` - Current session state
+
+## Troubleshooting
+
+### HUD shows 0% context/cost
+- Make sure the statusline hook is running (check `.claude/settings.local.json`)
+- Data syncs on each Claude Code request via the StatusLine hook
+
+### Agents not appearing
+- Run `/orient` in each Claude Code session to register agents
+- Check that `~/.anvil/agents.json` exists
+
+### Stale agents showing
+- Agents auto-mark as stale after 30 minutes of inactivity
+- Force refresh with `r` key
+
+## Related Commands
+- `/orient` - Register agent at session start
+- `/validate` - Check environment before work
+- `/handoff` - Preserve context before ending session
+
+## Future Enhancements (HUD v2)
+See spec at `.claude/specs/current/SPEC-ANV-HUD-v2.md` for planned features:
+- Cost attribution per issue
+- Quality gates panel (CI, tests, CodeRabbit)
+- Linear issue board integration
+- File lock coordination