anvil-dev-framework 0.1.6 → 0.1.7

package/README.md

@@ -1,7 +1,7 @@
 ```
      ___    _   ___     _____ _
     /   \  | \ | \ \   / /_ _| |
-   / /_\ \ |  \| |\ \ / / | || |      v0.1.6.0 (alpha)
+   / /_\ \ |  \| |\ \ / / | || |      v0.1.7.0 (alpha)
   / _____ \| |\  | \ V /  | || |___
  /_/     \_\_| \_|  \_/  |___|_____|
 
@@ -10,7 +10,7 @@
    ══════════════════════════════════════════════════════════
 ```
 
-# Anvil Development Framework <sup>v0.1.6.0</sup>
+# Anvil Development Framework <sup>v0.1.7.0</sup>
 
 > **A structured AI development system for solo builders who demand production-quality output.**
 
@@ -18,17 +18,18 @@ Anvil is a comprehensive framework for AI-assisted software development that com
 
 ---
 
-## 📦 Latest Changes in v0.1.6.0
+## 📦 Latest Changes in v0.1.7.0
 
-*Released: 2026-01-07*
+*Released: 2026-01-15*
 
-- **Ralph Wiggum Autonomous Execution** — Long-running unattended AI execution mode
-  - `/ralph start` — Initialize autonomous loop with task breakdown
-  - Circuit breaker safety (stops stuck loops automatically)
-  - Progress tracking to prevent repeated mistakes
-  - Git checkpointing before each restart
-- **PostToolUse Formatting Hook** — Auto-format files after Edit/Write operations
-- **Usage Guidelines** — Clear guidance on when Ralph is appropriate vs standard workflow
+- **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
 
 See [CHANGELOG.md](CHANGELOG.md) for complete history.
 
@@ -154,7 +155,7 @@ npm install -g anvil-dev-framework
 anvil init
 ```
 
-**Option 3: Homebrew (macOS)**
+**Option 3: Homebrew (macOS)** *(coming soon)*
 ```bash
 brew tap alexandercahiz/anvil
 brew install anvil

package/VERSION

@@ -1 +1 @@
-0.1.6.0
+0.1.7.1

package/docs/INSTALLATION.md

@@ -16,6 +16,24 @@ A context engineering framework that transforms Claude Code from a reactive assi
 
 ---
 
+## Quick Install
+
+For most users, the fastest way to get started:
+
+```bash
+# Using bun (recommended)
+bun install -g anvil-dev-framework
+anvil init
+
+# Or using npm
+npm install -g anvil-dev-framework
+anvil init
+```
+
+This installs the CLI and initializes your project with the Anvil framework. For customization options and detailed setup, continue reading below.
+
+---
+
 ## Background: Research Foundation
 
 This framework synthesizes patterns from 15+ production systems:

package/docs/command-reference.md

@@ -104,7 +104,7 @@ bun install -g anvil-dev-framework
 npm install -g anvil-dev-framework
 ```
 
-**Option 3: Homebrew (macOS)**
+**Option 3: Homebrew (macOS)** *(coming soon)*
 ```bash
 brew tap alexandercahiz/anvil
 brew install anvil

package/global/commands/orient.md

@@ -31,6 +31,35 @@ Options:
 
 ---
 
+## Post-Compaction Verification (CRITICAL)
+
+**ALWAYS run this before any file reads or edits after session resume:**
+
+```bash
+echo "=== Branch Verification ==="
+git branch --show-current
+
+echo "=== Working Tree Status ==="
+git status --short
+
+echo "=== Recent Changes ==="
+git diff --stat HEAD~3..HEAD 2>/dev/null || echo "No recent commits"
+```
+
+**Check results against expected context:**
+- Is this the branch mentioned in the handoff/summary?
+- Are there uncommitted changes that might conflict?
+- Do recent commits match expected work?
+
+**If mismatch detected:**
+1. STOP before making any edits
+2. Report discrepancy to user
+3. Switch branches or stash as needed
+
+**Why this matters**: In 10/20 recent retros, work was done on the wrong branch after context compaction. This step prevents hours of rework from branch confusion.
+
+---
+
 ## Manual Execution Steps (Fallback)
 
 Use these if orient_fast.py is unavailable (e.g., on main before PR merge).

package/global/lib/git_utils.py

@@ -0,0 +1,267 @@
+"""
+Git utility functions for safe repository operations.
+
+Provides helpers for common git operations that handle edge cases gracefully,
+such as untracked files blocking branch switches or divergent branches.
+
+Usage:
+    from git_utils import safe_checkout, get_repo_status, stash_changes
+
+    # Safe branch switch (auto-stashes if needed)
+    success, message = safe_checkout('main')
+
+    # Check repository status
+    status = get_repo_status()
+    if status['has_changes']:
+        print(f"Uncommitted changes in: {status['changed_files']}")
+"""
+
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+def run_git(*args: str, cwd: Optional[Path] = None) -> tuple[int, str, str]:
+    """
+    Run a git command and return (returncode, stdout, stderr).
+
+    Args:
+        *args: Git command arguments (e.g., 'status', '--porcelain')
+        cwd: Working directory (defaults to current directory)
+
+    Returns:
+        Tuple of (return_code, stdout, stderr)
+    """
+    result = subprocess.run(
+        ['git', *args],
+        capture_output=True,
+        text=True,
+        cwd=cwd
+    )
+    return result.returncode, result.stdout, result.stderr
+
+
+def get_current_branch(cwd: Optional[Path] = None) -> Optional[str]:
+    """Get the current git branch name, or None if not in a repo."""
+    code, stdout, _ = run_git('branch', '--show-current', cwd=cwd)
+    if code == 0:
+        return stdout.strip()
+    return None
+
+
+def get_repo_status(cwd: Optional[Path] = None) -> dict:
+    """
+    Get comprehensive repository status.
+
+    Returns:
+        Dictionary with:
+        - has_changes: bool - Any uncommitted changes
+        - has_staged: bool - Staged changes pending commit
+        - has_unstaged: bool - Modified files not staged
+        - has_untracked: bool - Untracked files present
+        - changed_files: list[str] - All changed file paths
+        - untracked_files: list[str] - Untracked file paths
+        - current_branch: str | None - Current branch name
+    """
+    code, stdout, _ = run_git('status', '--porcelain', cwd=cwd)
+
+    changed_files = []
+    untracked_files = []
+    has_staged = False
+    has_unstaged = False
+
+    if code == 0:
+        for line in stdout.splitlines():
+            if not line:
+                continue
+            status = line[:2]
+            filepath = line[3:]
+
+            changed_files.append(filepath)
+
+            if status.startswith('??'):
+                untracked_files.append(filepath)
+            else:
+                # First char is staged status, second is unstaged
+                if status[0] not in (' ', '?'):
+                    has_staged = True
+                if status[1] not in (' ', '?'):
+                    has_unstaged = True
+
+    return {
+        'has_changes': bool(changed_files),
+        'has_staged': has_staged,
+        'has_unstaged': has_unstaged,
+        'has_untracked': bool(untracked_files),
+        'changed_files': changed_files,
+        'untracked_files': untracked_files,
+        'current_branch': get_current_branch(cwd),
+    }
+
+
+def stash_changes(
+    message: Optional[str] = None,
+    include_untracked: bool = True,
+    cwd: Optional[Path] = None
+) -> tuple[bool, str]:
+    """
+    Stash current changes.
+
+    Args:
+        message: Optional stash message
+        include_untracked: Include untracked files in stash
+        cwd: Working directory
+
+    Returns:
+        Tuple of (success, message)
+    """
+    args = ['stash', 'push']
+    if include_untracked:
+        args.append('-u')
+    if message:
+        args.extend(['-m', message])
+
+    code, stdout, stderr = run_git(*args, cwd=cwd)
+
+    if code == 0:
+        return True, stdout.strip() or "Changes stashed"
+    return False, stderr.strip()
+
+
+def safe_checkout(
+    branch: str,
+    stash_if_needed: bool = True,
+    cwd: Optional[Path] = None
+) -> tuple[bool, str]:
+    """
+    Switch branches safely, stashing changes if needed.
+
+    This function handles the common case where uncommitted or untracked
+    files would block a branch switch by automatically stashing them first.
+
+    Args:
+        branch: Target branch name
+        stash_if_needed: Auto-stash changes before checkout (default True)
+        cwd: Working directory
+
+    Returns:
+        Tuple of (success, message) where message describes what happened
+
+    Examples:
+        >>> success, msg = safe_checkout('main')
+        >>> print(msg)
+        'Switched to main (changes stashed)'
+
+        >>> success, msg = safe_checkout('feature/new', stash_if_needed=False)
+        >>> print(msg)  # If changes present
+        'error: Your local changes would be overwritten...'
+    """
+    status = get_repo_status(cwd)
+    stash_created = False
+
+    if status['has_changes'] and stash_if_needed:
+        stash_msg = f"Auto-stash before checkout to {branch}"
+        success, stash_result = stash_changes(message=stash_msg, cwd=cwd)
+        if success:
+            stash_created = True
+        else:
+            return False, f"Failed to stash changes: {stash_result}"
+
+    # Attempt checkout
+    code, stdout, stderr = run_git('checkout', branch, cwd=cwd)
+
+    if code == 0:
+        msg = f"Switched to {branch}"
+        if stash_created:
+            msg += " (changes stashed)"
+        return True, msg
+    else:
+        # If stash was created but checkout failed, pop it back
+        if stash_created:
+            run_git('stash', 'pop', cwd=cwd)
+        return False, stderr.strip()
+
+
+def get_divergence_status(cwd: Optional[Path] = None) -> dict:
+    """
+    Check if local branch has diverged from remote.
+
+    Returns:
+        Dictionary with:
+        - ahead: int - Commits ahead of remote
+        - behind: int - Commits behind remote
+        - diverged: bool - True if both ahead and behind
+        - remote_branch: str | None - Tracked remote branch
+    """
+    # Get tracking branch
+    code, stdout, _ = run_git(
+        'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}',
+        cwd=cwd
+    )
+
+    if code != 0:
+        return {
+            'ahead': 0,
+            'behind': 0,
+            'diverged': False,
+            'remote_branch': None,
+        }
+
+    remote_branch = stdout.strip()
+
+    # Get ahead/behind counts
+    code, stdout, _ = run_git(
+        'rev-list', '--left-right', '--count', f'HEAD...{remote_branch}',
+        cwd=cwd
+    )
+
+    if code == 0:
+        parts = stdout.strip().split('\t')
+        ahead = int(parts[0]) if len(parts) > 0 else 0
+        behind = int(parts[1]) if len(parts) > 1 else 0
+    else:
+        ahead, behind = 0, 0
+
+    return {
+        'ahead': ahead,
+        'behind': behind,
+        'diverged': ahead > 0 and behind > 0,
+        'remote_branch': remote_branch,
+    }
+
+
+def list_stashes(cwd: Optional[Path] = None) -> list[dict]:
+    """
+    List all stashes with metadata.
+
+    Returns:
+        List of dicts with 'index', 'branch', 'message' keys
+    """
+    code, stdout, _ = run_git('stash', 'list', cwd=cwd)
+
+    stashes = []
+    if code == 0:
+        for line in stdout.splitlines():
+            if not line:
+                continue
+            # Format: stash@{0}: On branch-name: message
+            parts = line.split(': ', 2)
+            if len(parts) >= 2:
+                index = parts[0]  # stash@{0}
+                branch_part = parts[1] if len(parts) > 1 else ""
+                message = parts[2] if len(parts) > 2 else ""
+
+                # Extract branch name from "On branch-name" or "WIP on branch-name"
+                branch = ""
+                if branch_part.startswith("On "):
+                    branch = branch_part[3:]
+                elif branch_part.startswith("WIP on "):
+                    branch = branch_part[7:]
+
+                stashes.append({
+                    'index': index,
+                    'branch': branch,
+                    'message': message,
+                })
+
+    return stashes

package/global/lib/issue_models.py

@@ -255,3 +255,31 @@ class Issue:
 
     def __repr__(self) -> str:
         return f"Issue(identifier={self.identifier!r}, title={self.title!r}, status={self.status})"
+
+    def __getitem__(self, key: str):
+        """
+        Support dict-style access for ergonomic usage.
+
+        Example:
+            issue['identifier']  # Returns issue.identifier
+            issue['status']      # Returns issue.status
+
+        Raises:
+            KeyError: If the field doesn't exist on Issue
+        """
+        if hasattr(self, key):
+            return getattr(self, key)
+        raise KeyError(f"Issue has no field '{key}'")
+
+    def get(self, key: str, default=None):
+        """
+        Support safe dict-style access with default.
+
+        Example:
+            issue.get('identifier')           # Returns issue.identifier
+            issue.get('unknown', 'fallback')  # Returns 'fallback'
+        """
+        try:
+            return self[key]
+        except KeyError:
+            return default

package/global/lib/linear_provider.py

@@ -109,6 +109,13 @@ class LinearProvider(BaseProvider):
         self._team_id = team_id
         self.api_key = api_key or os.getenv("LINEAR_API_KEY")
 
+        # Validate team context is provided
+        if not team_key and not team_id:
+            raise ValueError(
+                "LinearProvider requires team_key or team_id. "
+                "Example: LinearProvider(team_key='ANV')"
+            )
+
         if not self.api_key:
             self._available = False
         elif requests is None:

package/global/lib/orient_fast.py

@@ -97,7 +97,12 @@ def check_linear_yaml() -> Optional[Dict[str, str]]:
 
 def check_git_state() -> Dict[str, Any]:
     """Get git status, branch, and recent commits."""
-    result = {"branch": "unknown", "clean": False, "recent_commits": []}
+    result: Dict[str, Any] = {
+        "branch": "unknown",
+        "clean": False,
+        "recent_commits": [],
+        "uncommitted_files": [],
+    }
 
     # Get branch
     branch_out, ok = run_command("git branch --show-current")
@@ -108,12 +113,21 @@ def check_git_state() -> Dict[str, Any]:
     status_out, ok = run_command("git status --porcelain")
     if ok:
         result["clean"] = len(status_out.strip()) == 0
+        if not result["clean"]:
+            # Capture uncommitted file list for warning
+            result["uncommitted_files"] = [
+                line.strip() for line in status_out.split("\n") if line.strip()
+            ][:5]  # Limit to 5 files
 
     # Get recent commits
     log_out, ok = run_command("git log --oneline -5")
     if ok and log_out:
         result["recent_commits"] = log_out.split("\n")[:5]
 
+    # Add compaction warning if uncommitted changes detected
+    if not result["clean"]:
+        result["warning"] = "Uncommitted changes detected - verify before proceeding"
+
     return result
 
 
@@ -398,6 +412,15 @@ def format_output(result: OrientResult, as_json: bool = False) -> str:
     clean_str = "clean" if git.get("clean") else "uncommitted changes"
     lines.append(f"**Git**: {git.get('branch', '?')} ({clean_str})")
 
+    # Post-compaction verification warning
+    if not git.get("clean"):
+        lines.append("\n**⚠️ Uncommitted Changes Detected**")
+        lines.append("Verify these are expected before proceeding with new work:")
+        for f in git.get("uncommitted_files", [])[:5]:
+            lines.append(f"  - {f}")
+        if git.get("warning"):
+            lines.append(f"_Note: {git.get('warning')}_\n")
+
     # Active agents
     if result.active_agents:
         lines.append(f"**Active Agents**: {len(result.active_agents)}")