invar-tools 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

invar/shell/prove_fallback.py

@@ -3,17 +3,70 @@ Hypothesis fallback for proof verification.
 
 DX-12: Provides Hypothesis as automatic fallback when CrossHair
 is unavailable, times out, or skips files.
+
+DX-22: Smart routing - detects C extension imports and routes
+directly to Hypothesis without wasting time on CrossHair.
 """
 
 from __future__ import annotations
 
 import subprocess
 import sys
+from dataclasses import dataclass, field
 from pathlib import Path
 
 from returns.result import Failure, Result, Success
 
+from invar.core.verification_routing import get_incompatible_imports
+
+
+@dataclass
+class FileRouting:
+    """DX-22: Classification of files for smart verification routing."""
+
+    crosshair_files: list[Path] = field(default_factory=list)
+    hypothesis_files: list[Path] = field(default_factory=list)
+    skip_files: list[Path] = field(default_factory=list)
+    incompatible_reasons: dict[str, set[str]] = field(default_factory=dict)
+
+
+# @shell_complexity: File I/O with error handling for import detection
+def classify_files_for_verification(files: list[Path]) -> FileRouting:
+    """
+    Classify files for smart verification routing.
+
+    DX-22: Detects C extension imports and routes files appropriately:
+    - Pure Python with contracts -> CrossHair (can prove)
+    - C extensions (numpy, pandas, etc.) -> Hypothesis (cannot prove)
+    - No contracts -> Skip
+
+    Returns FileRouting with classified files.
+    """
+    routing = FileRouting()
+
+    for file_path in files:
+        if not file_path.exists() or file_path.suffix != ".py":
+            routing.skip_files.append(file_path)
+            continue
+
+        try:
+            source = file_path.read_text()
+        except Exception:
+            routing.skip_files.append(file_path)
+            continue
+
+        # Check for incompatible imports
+        incompatible = get_incompatible_imports(source)
+        if incompatible:
+            routing.hypothesis_files.append(file_path)
+            routing.incompatible_reasons[str(file_path)] = incompatible
+        else:
+            routing.crosshair_files.append(file_path)
+
+    return routing
+
 
+# @shell_complexity: Fallback verification with hypothesis availability check
 def run_hypothesis_fallback(
     files: list[Path],
     max_examples: int = 100,
@@ -101,6 +154,8 @@ def run_hypothesis_fallback(
         return Failure(f"Hypothesis error: {e}")
 
 
+# @shell_orchestration: DX-22 smart routing + DX-12/13 fallback chain
+# @shell_complexity: Multiple verification phases with error handling paths
 def run_prove_with_fallback(
     files: list[Path],
     crosshair_timeout: int = 10,
@@ -109,9 +164,16 @@ def run_prove_with_fallback(
     cache_dir: Path | None = None,
 ) -> Result[dict, str]:
     """
-    Run proof verification with automatic Hypothesis fallback.
+    Run proof verification with smart routing and automatic fallback.
 
-    DX-12 + DX-13: Tries CrossHair first with optimizations, falls back to Hypothesis.
+    DX-22: Smart routing - routes C extension code directly to Hypothesis.
+    DX-12 + DX-13: CrossHair with caching, falls back to Hypothesis on failure.
+
+    Flow:
+        1. Classify files (CrossHair-compatible vs C-extension)
+        2. Run CrossHair on compatible files only
+        3. Run Hypothesis on incompatible files (no wasted CrossHair attempt)
+        4. Merge results with de-duplicated statistics
 
     Args:
         files: List of Python file paths to verify
@@ -121,63 +183,103 @@ def run_prove_with_fallback(
         cache_dir: Cache directory (default: .invar/cache/prove)
 
     Returns:
-        Success with verification results or Failure with error message
+        Success with verification results including routing statistics
     """
     # Import here to avoid circular import
     from invar.shell.prove import CrossHairStatus, run_crosshair_parallel
     from invar.shell.prove_cache import ProveCache
 
-    # DX-13: Initialize cache
+    # DX-22: Smart routing - classify files before verification
+    routing = classify_files_for_verification(files)
+
+    # Initialize result structure with DX-22 routing stats
+    result = {
+        "status": "passed",
+        "routing": {
+            "crosshair_files": len(routing.crosshair_files),
+            "hypothesis_files": len(routing.hypothesis_files),
+            "skip_files": len(routing.skip_files),
+            "incompatible_reasons": {
+                k: list(v) for k, v in routing.incompatible_reasons.items()
+            },
+        },
+        "crosshair": None,
+        "hypothesis": None,
+        "files": [str(f) for f in files],
+    }
+
+    # DX-13: Initialize cache for CrossHair
     cache = None
     if use_cache:
         if cache_dir is None:
             cache_dir = Path(".invar/cache/prove")
         cache = ProveCache(cache_dir=cache_dir)
 
-    # DX-13: Use parallel CrossHair with caching
-    crosshair_result = run_crosshair_parallel(
-        files,
-        max_iterations=5,  # Fast mode
-        max_workers=None,  # Auto-detect
-        cache=cache,
-    )
-
-    if isinstance(crosshair_result, Failure):
-        # CrossHair failed, try Hypothesis
-        return run_hypothesis_fallback(files, max_examples=hypothesis_max_examples)
-
-    result_data = crosshair_result.unwrap()
-    status = result_data.get("status", "")
-
-    # Check if we need fallback
-    needs_fallback = (
-        status == CrossHairStatus.SKIPPED
-        or status == CrossHairStatus.TIMEOUT
-        or "not installed" in result_data.get("reason", "")
-    )
-
-    if needs_fallback:
-        # Run Hypothesis as fallback
+    # Phase 1: Run CrossHair on compatible files
+    if routing.crosshair_files:
+        crosshair_result = run_crosshair_parallel(
+            routing.crosshair_files,
+            max_iterations=5,  # Fast mode
+            max_workers=None,  # Auto-detect
+            cache=cache,
+        )
+
+        if isinstance(crosshair_result, Success):
+            xh_data = crosshair_result.unwrap()
+            result["crosshair"] = xh_data
+
+            # Check if CrossHair needs fallback for any files
+            xh_status = xh_data.get("status", "")
+            needs_fallback = (
+                xh_status == CrossHairStatus.SKIPPED
+                or xh_status == CrossHairStatus.TIMEOUT
+                or "not installed" in xh_data.get("reason", "")
+            )
+
+            if needs_fallback:
+                # CrossHair failed, add these files to Hypothesis batch
+                routing.hypothesis_files.extend(routing.crosshair_files)
+                result["crosshair"]["fallback_triggered"] = True
+        else:
+            # CrossHair error, fallback all to Hypothesis
+            routing.hypothesis_files.extend(routing.crosshair_files)
+            result["crosshair"] = {
+                "status": "error",
+                "error": str(crosshair_result.failure()),
+                "fallback_triggered": True,
+            }
+
+    # Phase 2: Run Hypothesis on incompatible files + fallback files
+    if routing.hypothesis_files:
         hypothesis_result = run_hypothesis_fallback(
-            files, max_examples=hypothesis_max_examples
+            routing.hypothesis_files, max_examples=hypothesis_max_examples
         )
 
         if isinstance(hypothesis_result, Success):
-            hyp_data = hypothesis_result.unwrap()
-            # Merge results
-            return Success(
-                {
-                    "status": hyp_data.get("status", "unknown"),
-                    "primary_tool": "hypothesis",
-                    "crosshair_status": status,
-                    "crosshair_reason": result_data.get("reason", ""),
-                    "hypothesis_result": hyp_data,
-                    "files": [str(f) for f in files],
-                    "note": "CrossHair skipped/unavailable, used Hypothesis fallback",
-                }
-            )
-        return hypothesis_result
+            result["hypothesis"] = hypothesis_result.unwrap()
+        else:
+            result["hypothesis"] = {
+                "status": "error",
+                "error": str(hypothesis_result.failure()),
+            }
+            result["status"] = "failed"
+
+    # Determine overall status
+    xh_status = result.get("crosshair", {}).get("status", "passed")
+    hyp_status = result.get("hypothesis", {}).get("status", "passed")
+
+    if xh_status == "counterexample_found" or hyp_status == "failed":
+        result["status"] = "failed"
+    elif xh_status in ("error",) or hyp_status in ("error",):
+        result["status"] = "error"
+
+    # DX-22: Add de-duplicated statistics
+    result["stats"] = {
+        "crosshair_proven": len(
+            result.get("crosshair", {}).get("verified", [])
+        ),
+        "hypothesis_tested": len(routing.hypothesis_files),
+        "total_verified": len(files) - len(routing.skip_files),
+    }
 
-    # CrossHair succeeded (verified or found counterexample)
-    result_data["primary_tool"] = "crosshair"
-    return Success(result_data)
+    return Success(result)

invar/shell/templates.py

@@ -53,6 +53,7 @@ def get_template_path(name: str) -> Result[Path, str]:
         return Failure(f"Failed to get template path: {e}")
 
 
+# @shell_complexity: Template copy with path resolution
 def copy_template(
     template_name: str, dest: Path, dest_name: str | None = None
 ) -> Result[bool, str]:
@@ -73,6 +74,7 @@ def copy_template(
         return Failure(f"Failed to copy template: {e}")
 
 
+# @shell_complexity: Config addition with existing file detection
 def add_config(path: Path, console) -> Result[bool, str]:
     """Add configuration to project. Returns Success(True) if added, Success(False) if skipped."""
     pyproject = path / "pyproject.toml"
@@ -114,6 +116,7 @@ def create_directories(path: Path, console) -> None:
         console.print("[green]Created[/green] src/shell/")
 
 
+# @shell_complexity: Directory copy with file filtering
 def copy_examples_directory(dest: Path, console) -> Result[bool, str]:
     """Copy examples directory to .invar/examples/. Returns Success(True) if copied."""
     import shutil
@@ -139,6 +142,32 @@ def copy_examples_directory(dest: Path, console) -> Result[bool, str]:
         return Failure(f"Failed to copy examples: {e}")
 
 
+# @shell_complexity: Directory copy for Claude commands (DX-32)
+def copy_commands_directory(dest: Path, console) -> Result[bool, str]:
+    """Copy commands directory to .claude/commands/. Returns Success(True) if copied."""
+    import shutil
+
+    commands_dest = dest / ".claude" / "commands"
+    if commands_dest.exists():
+        return Success(False)
+
+    try:
+        commands_src = Path(str(resources.files("invar.templates").joinpath("commands")))
+        if not commands_src.exists():
+            return Failure("Commands template directory not found")
+
+        # Create .claude if needed
+        claude_dir = dest / ".claude"
+        if not claude_dir.exists():
+            claude_dir.mkdir()
+
+        shutil.copytree(commands_src, commands_dest)
+        console.print("[green]Created[/green] .claude/commands/ (Claude Code skills)")
+        return Success(True)
+    except OSError as e:
+        return Failure(f"Failed to copy commands: {e}")
+
+
 # Agent configuration for multi-agent support (DX-11, DX-17)
 AGENT_CONFIGS = {
     "claude": {
@@ -162,6 +191,7 @@ AGENT_CONFIGS = {
 }
 
 
+# @shell_complexity: Agent config detection across multiple locations
 def detect_agent_configs(path: Path) -> Result[dict[str, str], str]:
     """
     Detect existing agent configuration files.
@@ -195,6 +225,7 @@ def detect_agent_configs(path: Path) -> Result[dict[str, str], str]:
         return Failure(f"Failed to detect agent configs: {e}")
 
 
+# @shell_complexity: Reference addition with existing check
 def add_invar_reference(path: Path, agent: str, console) -> Result[bool, str]:
     """Add Invar reference to an existing agent config file."""
     if agent not in AGENT_CONFIGS:
@@ -220,6 +251,7 @@ def add_invar_reference(path: Path, agent: str, console) -> Result[bool, str]:
         return Failure(f"Failed to update {config['file']}: {e}")
 
 
+# @shell_complexity: Config creation with template selection
 def create_agent_config(path: Path, agent: str, console) -> Result[bool, str]:
     """
     Create agent config from template (DX-17).
@@ -248,6 +280,7 @@ def create_agent_config(path: Path, agent: str, console) -> Result[bool, str]:
     return Success(False)
 
 
+# @shell_complexity: MCP server config with JSON manipulation
 def configure_mcp_server(path: Path, console) -> Result[list[str], str]:
     """
     Configure MCP server for AI agents (DX-16).
@@ -407,6 +440,7 @@ The server communicates via stdio and should be managed by your AI agent.
 """
 
 
+# @shell_complexity: Git hooks installation with backup
 def install_hooks(path: Path, console) -> Result[bool, str]:
     """Install pre-commit hooks configuration and activate them."""
     import subprocess

invar/shell/test_cmd.py

@@ -26,6 +26,7 @@ def _detect_agent_mode() -> bool:
     return os.getenv("INVAR_MODE") == "agent" or not sys.stdout.isatty()
 
 
+# @shell_complexity: Test command with file collection and output
 def test(
     target: str = typer.Argument(None, help="File to test (optional with --changed)"),
     verbose: bool = typer.Option(False, "-v", "--verbose", help="Verbose output"),
@@ -33,7 +34,7 @@ def test(
     changed: bool = typer.Option(False, "--changed", help="Test git-modified files only"),
     max_examples: int = typer.Option(100, "--max-examples", help="Maximum Hypothesis examples per function"),
 ) -> None:
-    """Run property-based tests using Hypothesis on contracted functions (DX-08)."""
+    """Run property-based tests using Hypothesis on contracted functions."""
     from invar.shell.property_tests import (
         format_property_test_report,
         run_property_tests_on_files,
@@ -75,6 +76,7 @@ def test(
         raise typer.Exit(1)
 
 
+# @shell_complexity: Verify command with CrossHair integration
 def verify(
     target: str = typer.Argument(None, help="File to verify (optional with --changed)"),
     timeout: int = typer.Option(30, "--timeout", help="Timeout per function (seconds)"),

invar/shell/testing.py

@@ -40,7 +40,6 @@ __all__ = [
     "ProveCache",
     "VerificationLevel",
     "VerificationResult",
-    "detect_verification_context",
     "get_available_verifiers",
     "get_files_to_prove",
     "run_crosshair_on_files",
@@ -80,6 +79,7 @@ class VerificationResult:
     errors: list[str] = field(default_factory=list)
 
 
+# @shell_orchestration: Verifier discovery helper
 def get_available_verifiers() -> list[str]:
     """
     Detect installed verification tools.
@@ -111,21 +111,7 @@ def get_available_verifiers() -> list[str]:
     return available
 
 
-def detect_verification_context() -> VerificationLevel:
-    """
-    Auto-detect appropriate verification depth based on context.
-
-    DX-19: Simplified to 2 levels. Always returns STANDARD (full verification).
-    STATIC is only used when explicitly requested via --static flag.
-
-    >>> detect_verification_context() == VerificationLevel.STANDARD
-    True
-    """
-    # DX-19: Always use STANDARD (full verification) by default
-    # STATIC is only for explicit --static flag
-    return VerificationLevel.STANDARD
-
-
+# @shell_complexity: Doctest execution with subprocess and result parsing
 def run_doctests_on_files(
     files: list[Path], verbose: bool = False
 ) -> Result[dict, str]:
@@ -173,6 +159,7 @@ def run_doctests_on_files(
         return Failure(f"Doctest error: {e}")
 
 
+# @shell_complexity: Property test orchestration with subprocess
 def run_test(
     target: str, json_output: bool = False, verbose: bool = False
 ) -> Result[dict, str]:
@@ -230,6 +217,7 @@ def run_test(
         return Failure(f"Test error: {e}")
 
 
+# @shell_complexity: CrossHair verification with subprocess
 def run_verify(
     target: str, json_output: bool = False, timeout: int = 30
 ) -> Result[dict, str]:
@@ -266,9 +254,10 @@ def run_verify(
     try:
         result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout * 10)
 
+        # CrossHair format: "file:line: error: Err when calling func(...)"
         counterexamples = [
             line.strip() for line in result.stdout.split("\n")
-            if "error" in line.lower() or "counterexample" in line.lower()
+            if ": error:" in line.lower() or "counterexample" in line.lower()
         ]
 
         verify_result = {

invar/shell/update_cmd.py

@@ -21,6 +21,7 @@ console = Console()
 VERSION_PATTERN = re.compile(r"v(\d+)\.(\d+)(?:\.(\d+))?")
 
 
+# @shell_orchestration: Version parsing helper for update command
 def parse_version(text: str) -> tuple[int, int, int] | None:
     """
     Parse version string from text.
@@ -113,6 +114,7 @@ def update_examples(path: Path, console: Console) -> Result[bool, str]:
     return copy_examples_directory(path, console)
 
 
+# @shell_complexity: Update command with template comparison
 def update(
     path: Path = typer.Argument(Path(), help="Project root directory"),
     force: bool = typer.Option(

invar/templates/CLAUDE.md.template

@@ -1,21 +1,40 @@
 # Project Development Guide
 
-> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Session Start, ICIDIV workflow, and Task Completion requirements.
+> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion requirements.
 
-## Claude-Specific: Entry Verification
+## Check-In
 
-Your **first message** for any implementation task MUST include actual output from:
+Your first message MUST display:
 
 ```
-invar_guard(changed=true)   # or: invar guard --changed
-invar_map(top=10)           # or: invar map --top 10
+✓ Check-In: guard PASS | top: <entry1>, <entry2>
 ```
 
-**Use MCP tools if available**, otherwise use CLI commands.
+Execute `invar_guard(changed=true)` and `invar_map(top=10)`, then show this one-line summary.
 
-No output = Session not started correctly. Stop, execute tools, restart.
+Example:
+```
+✓ Check-In: guard PASS | top: parse_file, check_rules
+```
 
-This ensures you've followed the Session Start requirements in INVAR.md.
+This is your sign-in. The user sees it immediately.
+No visible check-in = Session not started.
+
+Then read `.invar/context.md` for project state and lessons learned.
+
+---
+
+## Final
+
+Your last message for an implementation task MUST display:
+
+```
+✓ Final: guard PASS | 0 errors, 2 warnings
+```
+
+Execute `invar_guard()` and show this one-line summary.
+
+This is your sign-out. Completes the Check-In/Final pair.
 
 ---
 
@@ -43,7 +62,44 @@ src/{project}/
 | INVAR.md | Invar | No | Protocol (`invar update` to sync) |
 | CLAUDE.md | User | Yes | Project customization (this file) |
 | .invar/context.md | User | Yes | Project state, lessons learned |
-| .invar/examples/ | Invar | No | **Must read:** Core/Shell patterns |
+| .invar/examples/ | Invar | No | **Must read:** Core/Shell patterns, workflow |
+
+## Visible Workflow (DX-30)
+
+For complex tasks (3+ functions), show 3 checkpoints in TodoList:
+
+```
+□ [UNDERSTAND] Task description, codebase context, constraints
+□ [SPECIFY] Contracts (@pre/@post) and design decomposition
+□ [VALIDATE] Guard results, Review Gate status, integration status
+```
+
+**BUILD is internal work** — not shown in TodoList.
+
+**Show contracts before code.** See `.invar/examples/workflow.md` for full example.
+
+---
+
+## Agent Roles
+
+| Command | Role | Purpose |
+|---------|------|---------|
+| `/review` | Reviewer | Adversarial code review (DX-31) |
+
+### Review Modes (Auto-Selected)
+
+`/review` automatically selects mode based on Guard output:
+
+| Condition | Mode | Behavior |
+|-----------|------|----------|
+| `review_suggested` triggered | **Isolated** | Task tool sub-agent (fresh context) |
+| No trigger | **Quick** | Same-context adversarial review |
+| `--isolated` flag | **Isolated** | Force isolation |
+| `--quick` flag | **Quick** | Force same-context |
+
+Guard triggers `review_suggested` for: security-sensitive files, escape hatches >= 3, contract coverage < 50%.
+
+---
 
 ## Project-Specific Rules