invar-tools 1.7.1__py3-none-any.whl → 1.8.0__py3-none-any.whl

invar/core/template_helpers.py

@@ -0,0 +1,32 @@
+"""
+Template transformation helpers.
+
+Core module: pure logic for template content transformations.
+"""
+
+from __future__ import annotations
+
+from deal import post
+
+
+@post(lambda result: "`" not in result or "\\`" in result)
+@post(lambda result: "${" not in result or "\\${" in result)
+def escape_for_js_template(content: str) -> str:
+    """
+    Escape content for JavaScript template literal.
+
+    Escapes backticks and ${} sequences that would be interpreted
+    by JavaScript template literals.
+
+    >>> escape_for_js_template("Hello `world`")
+    'Hello \\\\`world\\\\`'
+    >>> escape_for_js_template("Value: ${x}")
+    'Value: \\\\${x}'
+    >>> escape_for_js_template("Normal text")
+    'Normal text'
+    """
+    # Escape backticks
+    content = content.replace("`", "\\`")
+    # Escape ${} template expressions
+    content = content.replace("${", "\\${")
+    return content

invar/shell/commands/init.py

@@ -22,6 +22,7 @@ from invar.shell.mcp_config import (
     generate_mcp_json,
     get_recommended_method,
 )
+from invar.shell.pi_hooks import install_pi_hooks
 from invar.shell.templates import (
     add_config,
     create_directories,
@@ -55,12 +56,17 @@ FILE_CATEGORIES: dict[str, list[tuple[str, str]]] = {
     "generic": [
         ("AGENT.md", "Universal agent instructions"),
     ],
+    "pi": [
+        ("CLAUDE.md", "Agent instructions (Pi compatible)"),
+        (".claude/skills/", "Workflow automation (Pi compatible)"),
+        (".pi/hooks/", "Pi-specific hooks"),
+    ],
 }
 
 AGENT_CONFIGS: dict[str, dict[str, str]] = {
     "claude": {"name": "Claude Code", "category": "claude"},
+    "pi": {"name": "Pi Coding Agent", "category": "pi"},
     "generic": {"name": "Other (AGENT.md)", "category": "generic"},
-    # Future: "cursor", "windsurf", etc.
 }
 
 
@@ -103,6 +109,7 @@ def _prompt_agent_selection() -> list[str]:
 
     choices = [
         questionary.Choice("Claude Code (recommended)", value="claude"),
+        questionary.Choice("Pi Coding Agent", value="pi"),
         questionary.Choice("Other (AGENT.md)", value="generic"),
     ]
 
@@ -156,6 +163,8 @@ def _prompt_file_selection(agents: list[str]) -> dict[str, bool]:
         category_name = category.capitalize()
         if category == "claude":
             category_name = "Claude Code"
+        elif category == "pi":
+            category_name = "Pi Coding Agent"
         choices.append(questionary.Separator(f"── {category_name} ──"))
         for file, desc in files:
             choices.append(
@@ -241,6 +250,11 @@ def init(
         "--claude",
         help="Auto-select Claude Code, skip all prompts",
     ),
+    pi: bool = typer.Option(
+        False,
+        "--pi",
+        help="Auto-select Pi Coding Agent, skip all prompts",
+    ),
     preview: bool = typer.Option(
         False,
         "--preview",
@@ -252,6 +266,11 @@ def init(
 
     DX-70: Simplified init with interactive selection and safe merge.
 
+    \b
+    Quick setup options:
+    - --claude  Auto-select Claude Code (MCP + hooks + skills)
+    - --pi      Auto-select Pi (shares CLAUDE.md + skills, adds Pi hooks)
+
     \b
     This command is safe - it always MERGES with existing files:
     - File doesn't exist → Create
@@ -264,6 +283,11 @@ def init(
     """
     from invar import __version__
 
+    # Mutual exclusivity check
+    if claude and pi:
+        console.print("[red]Error:[/red] Cannot use --claude and --pi together.")
+        raise typer.Exit(1)
+
     # Resolve path
     if path == Path():
         path = Path.cwd()
@@ -272,6 +296,8 @@ def init(
     # Header
     if claude:
         console.print(f"\n[bold]Invar v{__version__} - Quick Setup (Claude Code)[/bold]")
+    elif pi:
+        console.print(f"\n[bold]Invar v{__version__} - Quick Setup (Pi)[/bold]")
     else:
         console.print(f"\n[bold]Invar v{__version__} - Project Setup[/bold]")
     console.print("=" * 45)
@@ -279,16 +305,23 @@ def init(
 
     # Determine agents and files
     if claude:
-        # Quick mode: use defaults
+        # Quick mode: Claude Code defaults
         agents = ["claude"]
         selected_files: dict[str, bool] = {}
         for category in ["optional", "claude"]:
             for file, _ in FILE_CATEGORIES.get(category, []):
                 selected_files[file] = True
+    elif pi:
+        # Quick mode: Pi defaults
+        agents = ["pi"]
+        selected_files = {}
+        for category in ["optional", "pi"]:
+            for file, _ in FILE_CATEGORIES.get(category, []):
+                selected_files[file] = True
     else:
         # Interactive mode
         if not _is_interactive():
-            console.print("[yellow]Non-interactive terminal detected. Use --claude for quick setup.[/yellow]")
+            console.print("[yellow]Non-interactive terminal detected. Use --claude or --pi for quick setup.[/yellow]")
             raise typer.Exit(1)
 
         agents = _prompt_agent_selection()
@@ -379,6 +412,10 @@ def init(
     if "claude" in agents and selected_files.get(".claude/hooks/", True):
         install_claude_hooks(path, console)
 
+    # Install Pi hooks if selected
+    if "pi" in agents and selected_files.get(".pi/hooks/", True):
+        install_pi_hooks(path, console)
+
     # Create MCP setup guide
     mcp_setup = invar_dir / "mcp-setup.md"
     if not mcp_setup.exists():
@@ -397,7 +434,7 @@ def init(
     # Completion message
     console.print(f"\n[bold green]✓ Initialized Invar v{__version__}[/bold green]")
 
-    # Show tip for Claude users
+    # Show agent-specific tips
     if "claude" in agents:
         console.print()
         console.print(
@@ -408,3 +445,13 @@ def init(
                 border_style="dim",
             )
         )
+    elif "pi" in agents:
+        console.print()
+        console.print(
+            Panel(
+                "[dim]Pi reads CLAUDE.md and .claude/skills/ directly.\n"
+                "Run [bold]pi[/bold] to start — USBV workflow is auto-enabled.[/dim]",
+                title="📌 Tip",
+                border_style="dim",
+            )
+        )

invar/shell/commands/uninstall.py

@@ -260,6 +260,23 @@ def collect_removal_targets(path: Path) -> dict:
                     (f".claude/hooks/{hook_file.name}", "hook, has invar marker")
                 )
 
+    # Pi hooks (LX-04)
+    pi_hooks_dir = path / ".pi" / "hooks"
+    if pi_hooks_dir.exists():
+        invar_ts = pi_hooks_dir / "invar.ts"
+        if invar_ts.exists():
+            targets["delete_files"].append((".pi/hooks/invar.ts", "Pi hook"))
+        # Check if .pi/hooks is empty after removal
+        if not any(f for f in pi_hooks_dir.iterdir() if f.name != "invar.ts"):
+            targets["delete_dirs"].append((".pi/hooks/", "empty after removal"))
+        # Check if .pi is empty
+        pi_dir = path / ".pi"
+        hooks_only = all(
+            child.name == "hooks" for child in pi_dir.iterdir() if child.is_dir()
+        )
+        if hooks_only:
+            targets["delete_dirs"].append((".pi/", "only had hooks"))
+
     # CLAUDE.md - delete if empty user region, otherwise modify
     claude_md = path / "CLAUDE.md"
     if claude_md.exists():

invar/shell/pi_hooks.py

@@ -0,0 +1,207 @@
+"""
+Pi Coding Agent hooks for Invar.
+
+LX-04: Full feature parity with Claude Code hooks.
+- pytest/crosshair blocking via tool_call
+- Protocol injection via pi.send() for long conversations
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from jinja2 import Environment, FileSystemLoader
+from returns.result import Failure, Result, Success
+
+from invar.core.template_helpers import escape_for_js_template
+from invar.shell.claude_hooks import detect_syntax, get_invar_md_content
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+# Pi hooks directory
+PI_HOOKS_DIR = ".pi/hooks"
+PROTOCOL_VERSION = "5.0"
+
+
+def get_pi_templates_path() -> Path:
+    """Get the path to Pi hook templates."""
+    return Path(__file__).parent.parent / "templates" / "hooks" / "pi"
+
+
+# @shell_complexity: Template rendering with protocol escaping
+def generate_pi_hook_content(project_path: Path) -> Result[str, str]:
+    """Generate Pi hook content from template."""
+    templates_path = get_pi_templates_path()
+    template_file = "invar.ts.jinja"
+
+    if not (templates_path / template_file).exists():
+        return Failure(f"Template not found: {template_file}")
+
+    try:
+        env = Environment(
+            loader=FileSystemLoader(str(templates_path)),
+            keep_trailing_newline=True,
+        )
+        template = env.get_template(template_file)
+
+        # Determine guard command based on syntax
+        syntax = detect_syntax(project_path)
+        guard_cmd = "invar_guard" if syntax == "mcp" else "invar guard"
+
+        # Get and escape protocol content for JS template literal
+        protocol_content = get_invar_md_content(project_path)
+        protocol_escaped = escape_for_js_template(protocol_content)
+
+        # Build context for template
+        context = {
+            "protocol_version": PROTOCOL_VERSION,
+            "generated_date": datetime.now().strftime("%Y-%m-%d"),
+            "guard_cmd": guard_cmd,
+            "invar_protocol_escaped": protocol_escaped,
+        }
+
+        content = template.render(**context)
+        return Success(content)
+    except Exception as e:
+        return Failure(f"Failed to generate Pi hook: {e}")
+
+
+def install_pi_hooks(
+    project_path: Path,
+    console: Console,
+) -> Result[list[str], str]:
+    """
+    Install Pi hooks for Invar.
+
+    Creates .pi/hooks/invar.ts with:
+    - pytest/crosshair blocking
+    - Protocol injection for long conversations
+    """
+    hooks_dir = project_path / PI_HOOKS_DIR
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+
+    console.print("\n[bold]Installing Pi hooks (LX-04)...[/bold]")
+    console.print("  Hooks will:")
+    console.print("    ✓ Block pytest/crosshair → redirect to invar guard")
+    console.print("    ✓ Refresh protocol in long conversations")
+    console.print("")
+
+    result = generate_pi_hook_content(project_path)
+    if isinstance(result, Failure):
+        console.print(f"  [red]Failed:[/red] {result.failure()}")
+        return Failure(result.failure())
+
+    content = result.unwrap()
+    hook_file = hooks_dir / "invar.ts"
+    hook_file.write_text(content)
+
+    console.print(f"  [green]Created[/green] {PI_HOOKS_DIR}/invar.ts")
+    console.print("\n  [bold green]✓ Pi hooks installed[/bold green]")
+    console.print("  [dim]Requires: Pi coding agent with hooks support[/dim]")
+    console.print("  [yellow]⚠ Restart Pi session for hooks to take effect[/yellow]")
+
+    return Success(["invar.ts"])
+
+
+# @shell_complexity: Version detection and conditional update logic
+def sync_pi_hooks(
+    project_path: Path,
+    console: Console,
+) -> Result[list[str], str]:
+    """
+    Update Pi hooks with current INVAR.md content.
+
+    Called during `invar init` to ensure hooks stay in sync with protocol.
+    Only updates if Pi hooks are already installed.
+    """
+    hooks_dir = project_path / PI_HOOKS_DIR
+    hook_file = hooks_dir / "invar.ts"
+
+    if not hook_file.exists():
+        return Success([])  # No hooks installed, nothing to sync
+
+    # Check version in existing hook
+    try:
+        existing_content = hook_file.read_text()
+        version_match = re.search(r"Protocol: v([\d.]+)", existing_content)
+        old_version = version_match.group(1) if version_match else "unknown"
+
+        if old_version != PROTOCOL_VERSION:
+            console.print(f"[cyan]Updating Pi hooks: v{old_version} → v{PROTOCOL_VERSION}[/cyan]")
+        else:
+            console.print("[dim]Refreshing Pi hooks...[/dim]")
+    except OSError:
+        pass
+
+    result = generate_pi_hook_content(project_path)
+    if isinstance(result, Failure):
+        console.print(f"  [yellow]Warning:[/yellow] Failed to generate Pi hook: {result.failure()}")
+        return Failure(result.failure())
+
+    content = result.unwrap()
+    hook_file.write_text(content)
+    console.print("[green]✓[/green] Pi hooks synced")
+
+    return Success(["invar.ts"])
+
+
+def remove_pi_hooks(
+    project_path: Path,
+    console: Console,
+) -> Result[None, str]:
+    """Remove Pi hooks."""
+    hooks_dir = project_path / PI_HOOKS_DIR
+    hook_file = hooks_dir / "invar.ts"
+
+    if hook_file.exists():
+        hook_file.unlink()
+        console.print(f"  [red]Removed[/red] {PI_HOOKS_DIR}/invar.ts")
+
+        # Remove directory if empty
+        try:
+            hooks_dir.rmdir()
+            console.print(f"  [red]Removed[/red] {PI_HOOKS_DIR}/")
+        except OSError:
+            pass  # Directory not empty, keep it
+
+        console.print("[bold green]✓ Pi hooks removed[/bold green]")
+    else:
+        console.print("[dim]No Pi hooks installed[/dim]")
+
+    return Success(None)
+
+
+def pi_hooks_status(
+    project_path: Path,
+    console: Console,
+) -> Result[dict[str, str], str]:
+    """Check status of Pi hooks."""
+    hooks_dir = project_path / PI_HOOKS_DIR
+    hook_file = hooks_dir / "invar.ts"
+
+    status: dict[str, str] = {}
+
+    if not hook_file.exists():
+        console.print("[dim]No Pi hooks installed[/dim]")
+        return Success({"status": "not_installed"})
+
+    status["status"] = "installed"
+
+    # Try to get version
+    try:
+        content = hook_file.read_text()
+        match = re.search(r"Protocol: v([\d.]+)", content)
+        if match:
+            version = match.group(1)
+            status["version"] = version
+            console.print(f"[green]✓ Pi hooks installed (v{version})[/green]")
+        else:
+            console.print("[green]✓ Pi hooks installed[/green]")
+    except OSError:
+        console.print("[green]✓ Pi hooks installed[/green]")
+
+    return Success(status)

invar/templates/config/AGENT.md.jinja

@@ -0,0 +1,198 @@
+<!--invar:critical-->
+## ⚡ Critical Rules
+
+| Always | Remember |
+|--------|----------|
+{% if syntax == "mcp" -%}
+| **Verify** | `invar_guard` — NOT pytest, NOT crosshair |
+{% else -%}
+| **Verify** | `invar guard` — NOT pytest, NOT crosshair |
+{% endif -%}
+| **Core** | `@pre/@post` + doctests, NO I/O imports |
+| **Shell** | Returns `Result[T, E]` from `returns` library |
+| **Flow** | USBV: Understand → Specify → Build → Validate |
+
+### Contract Rules (CRITICAL)
+
+```python
+# ❌ WRONG: Lambda must include ALL parameters
+@pre(lambda x: x >= 0)
+def calc(x: int, y: int = 0): ...
+
+# ✅ CORRECT: Include defaults too
+@pre(lambda x, y=0: x >= 0)
+def calc(x: int, y: int = 0): ...
+
+# ❌ WRONG: @post cannot access parameters
+@post(lambda result: result > x)  # 'x' not available!
+
+# ✅ CORRECT: @post only sees 'result'
+@post(lambda result: result >= 0)
+```
+
+<!--/invar:critical-->
+
+<!--invar:managed version="{{ version }}"-->
+# Project Development Guide
+
+> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion requirements.
+
+## Check-In
+
+> See [INVAR.md#check-in](./INVAR.md#check-in-required) for full protocol.
+
+**Your first message MUST display:** `✓ Check-In: [project] | [branch] | [clean/dirty]`
+
+**Actions:** Read `.invar/context.md`, then show status. Do NOT run guard at Check-In.
+
+---
+
+## Final
+
+Your last message for an implementation task MUST display:
+
+```
+✓ Final: guard PASS | 0 errors, 2 warnings
+```
+
+{% if syntax == "mcp" -%}
+Execute `invar_guard()` and show this one-line summary.
+{% else -%}
+Execute `invar guard` and show this one-line summary.
+{% endif %}
+
+This is your sign-out. Completes the Check-In/Final pair.
+
+---
+
+## Project Structure
+
+```
+src/{project}/
+├── core/    # Pure logic (@pre/@post, doctests, no I/O)
+└── shell/   # I/O operations (Result[T, E] return type)
+```
+
+**Key insight:** Core receives data (strings), Shell handles I/O (paths, files).
+
+## Quick Reference
+
+| Zone | Requirements |
+|------|-------------|
+| Core | `@pre`/`@post` + doctests, pure (no I/O) |
+| Shell | Returns `Result[T, E]` from `returns` library |
+
+### Core vs Shell (Edge Cases)
+
+- File/network/env vars → **Shell**
+- `datetime.now()`, `random` → **Inject param** OR Shell
+- Pure logic → **Core**
+
+> Full decision tree: [INVAR.md#core-shell](./INVAR.md#decision-tree-core-vs-shell)
+
+## Documentation Structure
+
+| File | Owner | Edit? | Purpose |
+|------|-------|-------|---------|
+| INVAR.md | Invar | No | Protocol (`invar update` to sync) |
+| AGENT.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, workflow |
+
+> **Before writing code:** Check Task Router in `.invar/context.md`
+
+## USBV Workflow
+
+For complex tasks (3+ functions), follow these phases:
+
+### 1. UNDERSTAND
+
+- **Intent:** What exactly needs to be done?
+{% if syntax == "mcp" -%}
+- **Inspect:** Use `invar_sig` to see existing contracts
+{% else -%}
+- **Inspect:** Use `invar sig` to see existing contracts
+{% endif -%}
+- **Context:** Read relevant code, understand patterns
+- **Constraints:** What must NOT change?
+
+### 2. SPECIFY
+
+- **Contracts FIRST:** Write `@pre`/`@post` before implementation
+- **Doctests:** Add examples for expected behavior
+- **Design:** Decompose complex tasks into sub-functions
+
+```python
+# SPECIFY before BUILD:
+@pre(lambda x: x > 0)
+@post(lambda result: result >= 0)
+def calculate(x: int) -> int:
+    """
+    >>> calculate(10)
+    100
+    """
+    ...  # Implementation comes in BUILD
+```
+
+### 3. BUILD
+
+- Follow the contracts written in SPECIFY
+{% if syntax == "mcp" -%}
+- Run `invar_guard(changed=true)` frequently
+{% else -%}
+- Run `invar guard --changed` frequently
+{% endif -%}
+- Commit after each logical unit
+
+### 4. VALIDATE
+
+{% if syntax == "mcp" -%}
+- Run `invar_guard()` (full verification)
+{% else -%}
+- Run `invar guard` (full verification)
+{% endif -%}
+- Integration works (if applicable)
+
+---
+
+## Tool Selection
+
+| I want to... | Use |
+|--------------|-----|
+{% if syntax == "mcp" -%}
+| See contracts | `invar_sig(target="<file>")` |
+| Find entry points | `invar_map(top=10)` |
+| Verify code | `invar_guard()` |
+{% else -%}
+| See contracts | `invar sig <file>` |
+| Find entry points | `invar map --top 10` |
+| Verify code | `invar guard` |
+{% endif -%}
+
+---
+
+## Task Completion
+
+A task is complete only when ALL conditions are met:
+- Check-In displayed: `✓ Check-In: [project] | [branch] | [clean/dirty]`
+- Intent explicitly stated
+- Contract written before implementation
+- Final displayed: `✓ Final: guard PASS | <errors>, <warnings>`
+- User requirement satisfied
+
+**Missing any = Task incomplete.**
+
+<!--/invar:managed-->
+<!--invar:project-->
+<!--/invar:project-->
+<!--invar:user-->
+<!-- ========================================================================
+     USER REGION - EDITABLE
+     Add your team conventions and project-specific rules below.
+     This section is preserved across `invar update` and `invar dev sync`.
+     ======================================================================== -->
+<!--/invar:user-->
+
+---
+
+*Generated by `invar init` v{{ version }}. Customize the user section freely.*

invar/templates/hooks/pi/invar.ts.jinja

@@ -0,0 +1,73 @@
+/**
+ * Invar Pi Hook
+ * Protocol: v{{ protocol_version }} | Generated: {{ generated_date }}
+ * LX-04: Full feature parity with Claude Code hooks
+ *
+ * Features:
+ * - pytest/crosshair blocking via tool_call
+ * - Protocol injection via pi.send() for long conversations
+ */
+
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+// Blocked commands (same as Claude Code)
+const BLOCKED_CMDS = [/^pytest\b/, /^python\s+-m\s+pytest/, /^crosshair\b/];
+const ALLOWED_FLAGS = [/--pdb/, /--cov/, /--debug/];
+
+// Protocol content for injection (escaped for JS)
+const INVAR_PROTOCOL = `{{ invar_protocol_escaped }}`;
+
+export default function (pi: HookAPI) {
+  let msgCount = 0;
+
+  // ============================================
+  // Session Management
+  // ============================================
+  pi.on("session", async (event) => {
+    // Reset count on session start/restore
+    if (event.reason === "start" || event.reason === "branch") {
+      msgCount = 0;
+    }
+  });
+
+  // ============================================
+  // Long Conversation Protocol Refresh
+  // ============================================
+  pi.on("agent_start", async () => {
+    msgCount++;
+
+    // Message 15: Lightweight checkpoint
+    if (msgCount === 15) {
+      pi.send(
+        "<system-reminder>Checkpoint: guard=verify, sig=contracts, USBV workflow.</system-reminder>"
+      );
+    }
+
+    // Message 25+: Full protocol injection every 10 messages
+    if (msgCount >= 25 && msgCount % 10 === 0) {
+      pi.send(`<system-reminder>
+=== Protocol Refresh (message ${msgCount}) ===
+${INVAR_PROTOCOL}
+</system-reminder>`);
+    }
+  });
+
+  // ============================================
+  // pytest/crosshair Blocking
+  // ============================================
+  pi.on("tool_call", async (event) => {
+    if (event.toolName !== "bash") return;
+    const cmd = ((event.input as Record<string, unknown>).command as string || "").trim();
+
+    // Skip if not a blocked command
+    if (!BLOCKED_CMDS.some((p) => p.test(cmd))) return;
+
+    // Allow if has debug/test flags
+    if (ALLOWED_FLAGS.some((p) => p.test(cmd))) return;
+
+    return {
+      block: true,
+      reason: "Use `{{ guard_cmd }}` instead of pytest/crosshair.",
+    };
+  });
+}

invar/templates/manifest.toml

@@ -54,6 +54,7 @@ extensions = { action = "preserve" }
 
 # Config files (Jinja2 templates)
 "CLAUDE.md" = { src = "config/CLAUDE.md.jinja", type = "jinja" }
+"AGENT.md" = { src = "config/AGENT.md.jinja", type = "jinja" }
 ".invar/context.md" = { src = "config/context.md.jinja", type = "jinja" }
 ".pre-commit-config.yaml" = { src = "config/pre-commit.yaml.jinja", type = "jinja" }
 

invar/templates/skills/develop/SKILL.md.jinja

@@ -10,9 +10,49 @@ _invar:
 # Development Mode
 
 > **Purpose:** Implement solution following USBV workflow with verification.
+> **Mindset:** CONTRACTS before code — no exceptions.
+
+## Scope Boundaries
+
+**This skill IS for:**
+- Implementing features ("add", "create", "build")
+- Fixing bugs ("fix", "resolve")
+- Modifying existing code ("update", "change")
+- Writing tests and contracts
+
+**This skill is NOT for:**
+- Exploring unclear requirements → switch to `/investigate`
+- Choosing between approaches → switch to `/propose`
+- Reviewing completed work → switch to `/review`
+
+**Drift detection:** If requirements are unclear → STOP, exit to `/investigate` first.
 
 ## Entry Actions (REQUIRED)
 
+### Session Restore (if continuing from summary)
+
+When conversation begins with a previous session summary:
+
+1. **ALWAYS display Check-In first** — even when continuing
+2. **Determine current phase** from todo items:
+   | Todo keywords | Phase |
+   |---------------|-------|
+   | "research", "understand", "analyze" | UNDERSTAND |
+   | "contract", "design", "specify" | SPECIFY |
+   | "implement", "code", "build" | BUILD |
+   | "verify", "test", "guard" | VALIDATE |
+3. **Display phase header** before resuming work
+4. **Re-read context.md** for project state
+
+```
+# Example session restore:
+✓ Check-In: Invar | Main | dirty
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → BUILD (3/4) [resumed]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
 ### Context Refresh (DX-54)
 
 Before any workflow action:
@@ -123,6 +163,25 @@ If any NO → Stop. Write contract first.
 
 ### 3. BUILD
 
+#### New Function Gate (MANDATORY)
+
+**Before writing ANY new Core function, STOP and verify:**
+
+| Check | If NO → Action |
+|-------|----------------|
+| Contract shown in SPECIFY phase? | ⛔ STOP. Return to SPECIFY. |
+| Doctest written? | ⛔ STOP. Write doctest first. |
+
+```
+⛔ GATE VIOLATION: Writing new function without prior contract.
+   → Return to SPECIFY phase. Show contract first.
+```
+
+**Exempt from gate:**
+- Shell functions (no @pre/@post required)
+- Editing existing functions (contract already exists)
+- Non-Python files
+
 **For complex tasks:** Enter Plan Mode first, get user approval.
 
 **Implementation rules:**

invar/templates/skills/investigate/SKILL.md.jinja

@@ -11,6 +11,21 @@ _invar:
 
 > **Purpose:** Understand before acting. Gather information, analyze code, report findings.
 
+## Scope Boundaries
+
+**This skill IS for:**
+- Understanding vague or unclear tasks
+- Analyzing existing code and architecture
+- Researching before implementation
+- Answering "why", "what", "how does" questions
+
+**This skill is NOT for:**
+- Writing or modifying code → switch to `/develop`
+- Making design decisions → switch to `/propose`
+- Reviewing code quality → switch to `/review`
+
+**Drift detection:** If you find yourself wanting to edit files → STOP, exit to `/develop`.
+
 ## Constraints
 
 **FORBIDDEN in this phase:**

invar/templates/skills/propose/SKILL.md.jinja

@@ -10,6 +10,39 @@ _invar:
 # Proposal Mode
 
 > **Purpose:** Facilitate human decision-making with clear options and trade-offs.
+> **Mindset:** OPTIONS, not decisions — human chooses.
+
+## Scope Boundaries
+
+**This skill IS for:**
+- Presenting design choices with trade-offs
+- Facilitating architectural decisions
+- Comparing approaches (A vs B)
+- Creating formal proposals for complex decisions
+
+**This skill is NOT for:**
+- Implementing the chosen option → switch to `/develop`
+- Researching to understand the problem → switch to `/investigate`
+- Reviewing existing code → switch to `/review`
+
+**Drift detection:** If you find yourself writing implementation code → STOP, wait for user choice, then exit to `/develop`.
+
+## Constraints
+
+**FORBIDDEN in this phase:**
+- Writing implementation code (beyond examples)
+- Making decisions for the user
+- Creating files other than proposals
+- Committing changes
+
+**ALLOWED:**
+- Read, Glob, Grep (research for options)
+{% if syntax == "mcp" -%}
+- invar_sig, invar_map (understand current state)
+{% else -%}
+- invar sig, invar map (understand current state)
+{% endif -%}
+- Creating proposal documents in `docs/proposals/`
 
 ## Entry Actions
 

invar/templates/skills/review/SKILL.md.jinja

@@ -14,6 +14,21 @@ _invar:
 > **Success Metric:** Issues FOUND, not code approved. Zero issues = you failed to look hard enough.
 > **Workflow:** AUTOMATIC Reviewer↔Fixer loop until quality_met or max_rounds (no human confirmation).
 
+## Scope Boundaries
+
+**This skill IS for:**
+- Finding bugs and logic errors in existing code
+- Verifying contract semantic value
+- Auditing escape hatches
+- Security review
+
+**This skill is NOT for:**
+- Implementing new features → switch to `/develop`
+- Understanding how code works → switch to `/investigate`
+- Deciding on architecture → switch to `/propose`
+
+**Drift detection:** If you're writing significant new code (not fixes) → STOP, you're in wrong skill.
+
 ## Auto-Loop Configuration
 
 ```

{invar_tools-1.7.1.dist-info → invar_tools-1.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.7.1
+Version: 1.8.0
 Summary: AI-native software engineering tools with design-by-contract verification
 Project-URL: Homepage, https://github.com/tefx/invar
 Project-URL: Documentation, https://github.com/tefx/invar#readme
@@ -138,8 +138,9 @@ cd your-project
 # Interactive mode - choose what to install
 uvx invar-tools init
 
-# Or quick setup for Claude Code (skip prompts)
-uvx invar-tools init --claude
+# Or quick setup (skip prompts)
+uvx invar-tools init --claude    # Claude Code
+uvx invar-tools init --pi        # Pi Coding Agent
 
 # Add runtime contracts to your project
 pip install invar-runtime
@@ -369,10 +370,13 @@ AlphaCodium · Parsel · Reflexion · Clover
 
 | Agent | Status | Setup |
 |-------|--------|-------|
-| **Claude Code** | ✅ Full | `invar init` → select Claude Code |
-| **Pi / Cursor** | 🚧 In progress | `invar init` → select Other, include `AGENT.md` in prompt |
+| **Claude Code** | ✅ Full | `invar init --claude` |
+| **Pi** | ✅ Full | `invar init --pi` |
+| **Cursor** | ✅ MCP | `invar init` → select Other, add MCP config |
 | **Other** | 📝 Manual | `invar init` → select Other, include `AGENT.md` in prompt |
 
+> **See also:** [Multi-Agent Guide](./docs/guides/multi-agent.md) for detailed integration instructions.
+
 ### Claude Code (Full Experience)
 
 All features auto-configured:
@@ -381,13 +385,24 @@ All features auto-configured:
 - Claude Code hooks (tool guidance, verification reminders)
 - Pre-commit hooks
 
-### Pi / Cursor (In Progress)
+### Pi (Full Support)
+
+Pi reads CLAUDE.md and .claude/skills/ directly, sharing configuration with Claude Code:
+- **Same instruction file** — CLAUDE.md (no separate AGENT.md needed)
+- **Same workflow skills** — .claude/skills/ work in Pi
+- **Pi-specific hooks** — .pi/hooks/invar.ts for pytest blocking and protocol refresh
+- **Protocol injection** — Long conversation support via `pi.send()`
+- Pre-commit hooks
+
+### Cursor (MCP + Rules)
 
-Currently available:
-- Protocol document (INVAR.md)
-- CLI verification (`invar guard`)
+Cursor users get full verification via MCP:
+- MCP tools (`invar_guard`, `invar_sig`, `invar_map`)
+- .cursor/rules/ for USBV workflow guidance
+- Hooks (beta) for pytest blocking
 - Pre-commit hooks
-- MCP server (manual configuration)
+
+> See [Cursor Guide](./docs/guides/cursor.md) for detailed setup.
 
 ### Other Editors (Manual)
 

{invar_tools-1.7.1.dist-info → invar_tools-1.8.0.dist-info}/RECORD

@@ -27,6 +27,7 @@ invar/core/strategies.py,sha256=2DPl0z2p_CBNd4RlSbZzTeAy6Dq6cpCiBCB2p5qHHkk,8798
 invar/core/suggestions.py,sha256=LCg2Dy9EHh_n1t9jATRZ0gTkgJkAEZk3vp2nuuCyr-s,15129
 invar/core/sync_helpers.py,sha256=kd6VyFAcpKfkVcbDk3GaBi2n0EWOGICz4VmdxwbshfI,7523
 invar/core/tautology.py,sha256=Pmn__a0Bt55W0lAQo1G5q8Ory9KuE23dRknKw45xxbs,9221
+invar/core/template_helpers.py,sha256=E1UT7ct0DaUFlfHr9oTBvW4xfxAiS81rbmZHSucPw4c,881
 invar/core/template_parser.py,sha256=vH3H8OX55scZ1hWh3xoA8oJMhgleKufCOhkTvsSuu_4,14730
 invar/core/timeout_inference.py,sha256=BS2fJGmwOrLpYZUku4qrizgNDSIXVLFBslW-6sRAvpc,3451
 invar/core/trivial_detection.py,sha256=KYP8jJb7QDeusAxFdX5NAML_H0NL5wLgMeBWDQmNqfU,6086
@@ -56,6 +57,7 @@ invar/shell/guard_output.py,sha256=v3gG5P-_47nIFo8eAMKwdA_hLf2KZ0cQ-45Z6JjKp4w,1
 invar/shell/mcp_config.py,sha256=-hC7Y5BGuVs285b6gBARk7ZyzVxHwPgXSyt_GoN0jfs,4580
 invar/shell/mutation.py,sha256=Lfyk2b8j8-hxAq-iwAgQeOhr7Ci6c5tRF1TXe3CxQCs,8914
 invar/shell/pattern_integration.py,sha256=pRcjfq3NvMW_tvQCnaXZnD1k5AVEWK8CYOE2jN6VTro,7842
+invar/shell/pi_hooks.py,sha256=ln71f6SkjQ_7pMt6_udzeqgRaRIk3Y11XobLURBP2v0,6597
 invar/shell/property_tests.py,sha256=N9JreyH5PqR89oF5yLcX7ZAV-Koyg5BKo-J05-GUPsA,9109
 invar/shell/subprocess_env.py,sha256=9oXl3eMEbzLsFEgMHqobEw6oW_wV0qMEP7pklwm58Pw,11453
 invar/shell/template_engine.py,sha256=IzOiGsKVFo0lDUdtg27wMzIJJKToclv151RDZuDnHHo,11027
@@ -64,14 +66,14 @@ invar/shell/testing.py,sha256=rTNBH0Okh2qtG9ohSXOz487baQ2gXrWT3s_WECW3HJs,11143
 invar/shell/commands/__init__.py,sha256=MEkKwVyjI9DmkvBpJcuumXo2Pg_FFkfEr-Rr3nrAt7A,284
 invar/shell/commands/guard.py,sha256=vDBGOFb9mQ1D8eXrMvQB505GpjO1XLeCLrv2ig9-6dU,21718
 invar/shell/commands/hooks.py,sha256=W-SOnT4VQyUvXwipozkJwgEYfiOJGz7wksrbcdWegUg,2356
-invar/shell/commands/init.py,sha256=wAPPIDpoJyNOhrD09LldRg8w76mWv0r5qTcqlPWc920,13411
+invar/shell/commands/init.py,sha256=ASl01hIYW3Dt_d5XhYPwDfdRujbKvBGfK8B9Sf4eXq0,15117
 invar/shell/commands/merge.py,sha256=nuvKo8m32-OL-SCQlS4SLKmOZxQ3qj-1nGCx1Pgzifw,8183
 invar/shell/commands/mutate.py,sha256=GwemiO6LlbGCBEQsBFnzZuKhF-wIMEl79GAMnKUWc8U,5765
 invar/shell/commands/perception.py,sha256=TyH_HpqyKkmE3-zcU4YyBG8ghwJaSFeRC-OQMVBDTbQ,3837
 invar/shell/commands/sync_self.py,sha256=nmqBry7V2_enKwy2zzHg8UoedZNicLe3yKDhjmBeZ68,3880
 invar/shell/commands/template_sync.py,sha256=wVZ-UvJ1wpN2UBcWMfbei0n46XHYx-zRbMA2oX6FSi4,13723
 invar/shell/commands/test.py,sha256=goMf-ovvzEyWQMheq4YlJ-mwK5-w3lDj0cq0IA_1-_c,4205
-invar/shell/commands/uninstall.py,sha256=u1fqE2jCod2KxFMEYbtC4UFK1zuxzoaQKQzZdAjQcDE,17368
+invar/shell/commands/uninstall.py,sha256=Q2tDbGLUf0PC2xxWqmuBYwfxX7IuSQ_SmyxvwYcDyPo,18102
 invar/shell/commands/update.py,sha256=0V5F8vxQ6PHPHPVYDmxdRD7xXeQEFypiJMYpY5ryiek,1349
 invar/shell/prove/__init__.py,sha256=ZqlbmyMFJf6yAle8634jFuPRv8wNvHps8loMlOJyf8A,240
 invar/shell/prove/accept.py,sha256=cnY_6jzU1EBnpLF8-zWUWcXiSXtCwxPsXEYXsSVPG38,3717
@@ -81,10 +83,11 @@ invar/shell/prove/hypothesis.py,sha256=QUclOOUg_VB6wbmHw8O2EPiL5qBOeBRqQeM04AVuL
 invar/templates/CLAUDE.md.template,sha256=eaGU3SyRO_NEifw5b26k3srgQH4jyeujjCJ-HbM36_w,4913
 invar/templates/__init__.py,sha256=cb3ht8KPK5oBn5oG6HsTznujmo9WriJ_P--fVxJwycc,45
 invar/templates/context.md.template,sha256=FKyI1ghpqcf4wftyv9-auIFHor8Nm8lETN45Ja-L8Og,2386
-invar/templates/manifest.toml,sha256=cEe7yEOOeaLmOF-PrwZXxiPGjHhsSJYkWBKRHDmSbac,4268
+invar/templates/manifest.toml,sha256=afovCokbqEh0nyDGdIp1LqTUslJdC8T2HY6MV-NvegY,4331
 invar/templates/proposal.md.template,sha256=UP7SpQ7gk8jVlHGLQCSQ5c-kCj1DBQEz8M-vEStK77I,1573
 invar/templates/commands/audit.md,sha256=OrotO8420zTKnlNyAyL1Eos0VIaihzEU4AHdfDv68Oc,4162
 invar/templates/commands/guard.md,sha256=N_C_AXd9kI85W1B0aTEycjiDp_jdaP8eeq8O0FQ_WQ8,1227
+invar/templates/config/AGENT.md.jinja,sha256=tadNeX5G_XLLdbLiG1JSQm_Xjmt1kAJ3IrTaw_sDU9g,5275
 invar/templates/config/CLAUDE.md.jinja,sha256=VbtDWxn3H8qiE9-DV1hlG3DJ-GcBQU4ZiUHbFh6Bxxk,7814
 invar/templates/config/context.md.jinja,sha256=_kJ8erEQNJMLDCKrv4BXWkO6OaGzE-zW9biCf7144aY,3103
 invar/templates/config/pre-commit.yaml.jinja,sha256=nUPxLxkTHAgZwhFAuOMDbZ8v0NQV9FlQPbr2MDEOsoA,1778
@@ -98,15 +101,16 @@ invar/templates/hooks/PreToolUse.sh.jinja,sha256=D39PaT1eFSjz_Av16xK1atoBZbhLI8t
 invar/templates/hooks/Stop.sh.jinja,sha256=3S6lLeAGIu5aPQVRz4jjFS9AfjCD9DdS_jagmkw-x8Q,960
 invar/templates/hooks/UserPromptSubmit.sh.jinja,sha256=eAQqQ-XdOCyhLpF5_1r1z7C-Ej9GQ5Isqbu_2LAtsno,2302
 invar/templates/hooks/__init__.py,sha256=RnnMoQA-8eqbr8Y_1Vu9B8h5vAz4C-vmo8wgdcGYrz0,43
+invar/templates/hooks/pi/invar.ts.jinja,sha256=D1TRxHuNkmjhICPOxjcyoRUZryyz7MpfIvBLjm-krjA,2234
 invar/templates/protocol/INVAR.md,sha256=ppQhb_-R5YaXAqW1WDMOcXptx-CrAQI_xYxld7YljK8,9998
-invar/templates/skills/develop/SKILL.md.jinja,sha256=3coPSZGh1-YKN9Xc_xcEkfEP3S0XiFMMGF0hJZEaAx8,10562
-invar/templates/skills/investigate/SKILL.md.jinja,sha256=bOLdLMH5WUVBYOo4NpsfyvI6xx7I1lCNr_X-8bMe_kg,2744
-invar/templates/skills/propose/SKILL.md.jinja,sha256=_iDLYN6-cfzA8n0_8sv-Dnpm1xq9IIpcDyM10mU2WUA,2420
-invar/templates/skills/review/SKILL.md.jinja,sha256=e7HULz1jjLOlk2LYejQMk2F-cu7dDIwvh6lWNjx3j-Q,14123
-invar_tools-1.7.1.dist-info/METADATA,sha256=dBk4N2qRISfYrc6Rr66eY08_me9Rqfyq34RDBCaEj1s,17600
-invar_tools-1.7.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-invar_tools-1.7.1.dist-info/entry_points.txt,sha256=RwH_EhqgtFPsnO6RcrwrAb70Zyfb8Mh6uUtztWnUxGk,102
-invar_tools-1.7.1.dist-info/licenses/LICENSE,sha256=qeFksp4H4kfTgQxPCIu3OdagXyiZcgBlVfsQ6M5oFyk,10767
-invar_tools-1.7.1.dist-info/licenses/LICENSE-GPL,sha256=IvZfC6ZbP7CLjytoHVzvpDZpD-Z3R_qa1GdMdWlWQ6Q,35157
-invar_tools-1.7.1.dist-info/licenses/NOTICE,sha256=joEyMyFhFY8Vd8tTJ-a3SirI0m2Sd0WjzqYt3sdcglc,2561
-invar_tools-1.7.1.dist-info/RECORD,,
+invar/templates/skills/develop/SKILL.md.jinja,sha256=kCKXTgHtfqED__Udn3dM6OxG0FQZx1NsjFhHtDNExJA,12558
+invar/templates/skills/investigate/SKILL.md.jinja,sha256=cp6TBEixBYh1rLeeHOR1yqEnFqv1NZYePORMnavLkQI,3231
+invar/templates/skills/propose/SKILL.md.jinja,sha256=6BuKiCqO1AEu3VtzMHy1QWGqr_xqG9eJlhbsKT4jev4,3463
+invar/templates/skills/review/SKILL.md.jinja,sha256=OvKoomS4MJHYbTuWSZjmeS_q_Wh6uNHzjXaewj6ELEg,14596
+invar_tools-1.8.0.dist-info/METADATA,sha256=51-iej0SZ6ramV9uMvwlxBUZYbXTQAUc1Mi5GHJGvDw,18295
+invar_tools-1.8.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+invar_tools-1.8.0.dist-info/entry_points.txt,sha256=RwH_EhqgtFPsnO6RcrwrAb70Zyfb8Mh6uUtztWnUxGk,102
+invar_tools-1.8.0.dist-info/licenses/LICENSE,sha256=qeFksp4H4kfTgQxPCIu3OdagXyiZcgBlVfsQ6M5oFyk,10767
+invar_tools-1.8.0.dist-info/licenses/LICENSE-GPL,sha256=IvZfC6ZbP7CLjytoHVzvpDZpD-Z3R_qa1GdMdWlWQ6Q,35157
+invar_tools-1.8.0.dist-info/licenses/NOTICE,sha256=joEyMyFhFY8Vd8tTJ-a3SirI0m2Sd0WjzqYt3sdcglc,2561
+invar_tools-1.8.0.dist-info/RECORD,,