invar-tools 1.7.0__tar.gz → 1.8.0__tar.gz

{invar_tools-1.7.0 → invar_tools-1.8.0}/.claude/hooks/invar.PostToolUse.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Invar PostToolUse Hook
-# Protocol: v5.0 | Generated: 2025-12-29
+# Protocol: v5.0 | Generated: 2025-12-30
 # DX-57: Git-based change detection with fallback
 
 TOOL_NAME="$1"

{invar_tools-1.7.0 → invar_tools-1.8.0}/.claude/hooks/invar.PreToolUse.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Invar PreToolUse Hook
-# Protocol: v5.0 | Generated: 2025-12-29
+# Protocol: v5.0 | Generated: 2025-12-30
 # DX-57: Smart blocking with auto-escape for pytest/crosshair
 
 TOOL_NAME="$1"

{invar_tools-1.7.0 → invar_tools-1.8.0}/.claude/hooks/invar.Stop.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Invar Stop Hook
-# Protocol: v5.0 | Generated: 2025-12-29
+# Protocol: v5.0 | Generated: 2025-12-30
 # DX-57: Session cleanup and unverified changes warning
 
 # Use session-specific state

{invar_tools-1.7.0 → invar_tools-1.8.0}/.claude/hooks/invar.UserPromptSubmit.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Invar UserPromptSubmit Hook
-# Protocol: v5.0 | Generated: 2025-12-29
+# Protocol: v5.0 | Generated: 2025-12-30
 # DX-57: Protocol refresh with full INVAR.md injection
 
 USER_MESSAGE="$1"
@@ -340,6 +340,7 @@ invar guard              # Full: static + doctests + CrossHair + Hypothesis
 invar guard --static     # Static only (quick debug, ~0.5s)
 invar guard --changed    # Modified files only
 invar guard --coverage   # Collect branch coverage
+invar guard -c           # Contract coverage only (DX-63)
 invar sig <file>         # Show contracts + signatures
 invar map --top 10       # Most-referenced symbols
 invar rules              # List all rules with detection/hints (JSON)

{invar_tools-1.7.0 → invar_tools-1.8.0}/.claude/skills/develop/SKILL.md

@@ -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:
@@ -106,6 +146,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_tools-1.7.0 → invar_tools-1.8.0}/.claude/skills/investigate/SKILL.md

@@ -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_tools-1.7.0 → invar_tools-1.8.0}/.claude/skills/propose/SKILL.md

@@ -10,6 +10,35 @@ _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)
+- invar_sig, invar_map (understand current state)
+- Creating proposal documents in `docs/proposals/`
 
 ## Entry Actions
 

{invar_tools-1.7.0 → invar_tools-1.8.0}/.claude/skills/review/SKILL.md

@@ -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.0 → invar_tools-1.8.0}/CLAUDE.md

@@ -264,6 +264,24 @@ pip install -e runtime/    # Runtime in dev mode
      Add your team conventions and project-specific rules below.
      This section is preserved across `invar update` and `invar dev sync`.
      ======================================================================== -->
+
+## Code Style
+
+Run `ruff check --fix` frequently after changing code to fix lint issues before commit.
+
+## Session Restore
+
+When continuing from a previous session summary:
+
+1. **ALWAYS display Check-In first**
+2. **Infer current phase** from todo keywords:
+   - "research/understand" → UNDERSTAND
+   - "contract/design" → SPECIFY
+   - "implement/code" → BUILD
+   - "verify/test" → VALIDATE
+3. **Display phase header** before resuming work
+4. **Re-read context.md** for project state
+
 <!--/invar:user-->
 
 ---

{invar_tools-1.7.0 → invar_tools-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.7.0
+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
@@ -28,6 +28,7 @@ Requires-Dist: jinja2>=3.0
 Requires-Dist: mcp>=1.0
 Requires-Dist: pre-commit>=3.0
 Requires-Dist: pydantic>=2.0
+Requires-Dist: questionary>=2.0
 Requires-Dist: returns>=0.20
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.9
@@ -129,35 +130,25 @@ Guard passed.
 
 **Why uvx?** Always uses latest version, doesn't pollute project dependencies, auto-detects your project's venv.
 
-### 🆕 New Project
+### 🎯 Setup
 
 ```bash
-# 1. Enter your project directory
 cd your-project
 
-# 2. Initialize with Claude Code (full experience)
-uvx invar-tools init --claude
+# Interactive mode - choose what to install
+uvx invar-tools init
 
-# 3. Add runtime contracts to your project
-pip install invar-runtime
-# Or add to pyproject.toml: dependencies = ["invar-runtime"]
+# Or quick setup (skip prompts)
+uvx invar-tools init --claude    # Claude Code
+uvx invar-tools init --pi        # Pi Coding Agent
 
-# 4. Start coding with AI
+# Add runtime contracts to your project
+pip install invar-runtime
 ```
 
-### 📁 Existing Project
-
-```bash
-cd your-project
-
-# Update managed files, preserve your customizations
-uvx invar-tools init --claude
-
-# Or without Claude Code integration
-uvx invar-tools init
-```
+**Safe and idempotent** — Run `invar init` anytime. It always **merges** with existing files, preserving your content.
 
-Invar's init is idempotent—safe to run multiple times. It detects existing configuration and updates only managed regions.
+> 💡 **After `claude /init`?** Just run `invar init` again to restore Invar configuration.
 
 ### 💬 Example Interaction
 
@@ -375,39 +366,71 @@ AlphaCodium · Parsel · Reflexion · Clover
 
 ---
 
-## 🖥️ Platform Experience
+## 🖥️ Agent Support
 
-| Feature | Claude Code | Other Editors |
-|---------|-------------|---------------|
-| CLI verification (`invar guard`) | ✅ | ✅ |
-| Protocol document (INVAR.md) | ✅ | ✅ |
-| MCP tool integration | ✅ Auto-configured | Manual setup possible |
-| Workflow skills | ✅ Auto-configured | Include in system prompt |
-| Pre-commit hooks | ✅ | ✅ |
-| Sub-agent review | ✅ | — |
+| Agent | Status | Setup |
+|-------|--------|-------|
+| **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 |
 
-**Claude Code** provides the full experience—MCP tools, skill routing, and hooks are auto-configured by `invar init --claude`.
+> **See also:** [Multi-Agent Guide](./docs/guides/multi-agent.md) for detailed integration instructions.
 
-**Other editors** can achieve similar results by:
-1. Adding INVAR.md content to system prompts
-2. Manually configuring MCP servers (if supported)
-3. Using CLI commands for verification
+### Claude Code (Full Experience)
+
+All features auto-configured:
+- MCP tools (`invar_guard`, `invar_sig`, `invar_map`)
+- Workflow skills (`/develop`, `/review`, `/investigate`, `/propose`)
+- Claude Code hooks (tool guidance, verification reminders)
+- Pre-commit hooks
+
+### 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)
+
+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
+
+> See [Cursor Guide](./docs/guides/cursor.md) for detailed setup.
+
+### Other Editors (Manual)
+
+1. Run `invar init` → select "Other (AGENT.md)"
+2. Include generated `AGENT.md` in your agent's prompt
+3. Configure MCP server if supported
+4. Use CLI commands (`invar guard`) for verification
 
 ---
 
 ## 📂 What Gets Installed
 
-`invar init --claude` creates:
+`invar init` creates (select in interactive mode):
+
+| File/Directory | Purpose | Category |
+|----------------|---------|----------|
+| `INVAR.md` | Protocol for AI agents | Required |
+| `.invar/` | Config, context, examples | Required |
+| `.pre-commit-config.yaml` | Verification before commit | Optional |
+| `src/core/`, `src/shell/` | Recommended structure | Optional |
+| `CLAUDE.md` | Agent instructions | Claude Code |
+| `.claude/skills/` | Workflow automation | Claude Code |
+| `.claude/commands/` | User commands (/audit, /guard) | Claude Code |
+| `.claude/hooks/` | Tool guidance | Claude Code |
+| `.mcp.json` | MCP server config | Claude Code |
+| `AGENT.md` | Universal agent instructions | Other agents |
 
-| File/Directory | Purpose | Editable? |
-|----------------|---------|-----------|
-| `INVAR.md` | Protocol for AI agents | No (managed) |
-| `CLAUDE.md` | Project configuration | Yes |
-| `.claude/skills/` | Workflow skills | Yes |
-| `.claude/hooks/` | Tool call interception | Yes |
-| `.invar/examples/` | Reference patterns | No (managed) |
-| `.invar/context.md` | Project state, lessons | Yes |
-| `pyproject.toml` | `[tool.invar]` section | Yes |
+**Note:** If `pyproject.toml` exists, Guard configuration goes there as `[tool.invar.guard]` instead of `.invar/config.toml`.
 
 **Recommended structure:**
 
@@ -473,7 +496,9 @@ rules = ["missing_contract", "shell_result"]
 | `invar guard` | Full verification (static + doctest + property + symbolic) |
 | `invar guard --changed` | Only git-modified files |
 | `invar guard --static` | Static analysis only (~0.5s) |
-| `invar init` | Initialize or update project |
+| `invar init` | Initialize or update project (interactive) |
+| `invar init --claude` | Quick setup for Claude Code |
+| `invar uninstall` | Remove Invar from project (preserves user content) |
 | `invar sig <file>` | Show signatures and contracts |
 | `invar map` | Symbol map with reference counts |
 | `invar rules` | List all rules |

{invar_tools-1.7.0 → invar_tools-1.8.0}/README.md

@@ -88,35 +88,25 @@ Guard passed.
 
 **Why uvx?** Always uses latest version, doesn't pollute project dependencies, auto-detects your project's venv.
 
-### 🆕 New Project
+### 🎯 Setup
 
 ```bash
-# 1. Enter your project directory
 cd your-project
 
-# 2. Initialize with Claude Code (full experience)
-uvx invar-tools init --claude
+# Interactive mode - choose what to install
+uvx invar-tools init
 
-# 3. Add runtime contracts to your project
-pip install invar-runtime
-# Or add to pyproject.toml: dependencies = ["invar-runtime"]
+# Or quick setup (skip prompts)
+uvx invar-tools init --claude    # Claude Code
+uvx invar-tools init --pi        # Pi Coding Agent
 
-# 4. Start coding with AI
+# Add runtime contracts to your project
+pip install invar-runtime
 ```
 
-### 📁 Existing Project
-
-```bash
-cd your-project
-
-# Update managed files, preserve your customizations
-uvx invar-tools init --claude
-
-# Or without Claude Code integration
-uvx invar-tools init
-```
+**Safe and idempotent** — Run `invar init` anytime. It always **merges** with existing files, preserving your content.
 
-Invar's init is idempotent—safe to run multiple times. It detects existing configuration and updates only managed regions.
+> 💡 **After `claude /init`?** Just run `invar init` again to restore Invar configuration.
 
 ### 💬 Example Interaction
 
@@ -334,39 +324,71 @@ AlphaCodium · Parsel · Reflexion · Clover
 
 ---
 
-## 🖥️ Platform Experience
+## 🖥️ Agent Support
 
-| Feature | Claude Code | Other Editors |
-|---------|-------------|---------------|
-| CLI verification (`invar guard`) | ✅ | ✅ |
-| Protocol document (INVAR.md) | ✅ | ✅ |
-| MCP tool integration | ✅ Auto-configured | Manual setup possible |
-| Workflow skills | ✅ Auto-configured | Include in system prompt |
-| Pre-commit hooks | ✅ | ✅ |
-| Sub-agent review | ✅ | — |
+| Agent | Status | Setup |
+|-------|--------|-------|
+| **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 |
 
-**Claude Code** provides the full experience—MCP tools, skill routing, and hooks are auto-configured by `invar init --claude`.
+> **See also:** [Multi-Agent Guide](./docs/guides/multi-agent.md) for detailed integration instructions.
 
-**Other editors** can achieve similar results by:
-1. Adding INVAR.md content to system prompts
-2. Manually configuring MCP servers (if supported)
-3. Using CLI commands for verification
+### Claude Code (Full Experience)
+
+All features auto-configured:
+- MCP tools (`invar_guard`, `invar_sig`, `invar_map`)
+- Workflow skills (`/develop`, `/review`, `/investigate`, `/propose`)
+- Claude Code hooks (tool guidance, verification reminders)
+- Pre-commit hooks
+
+### 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)
+
+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
+
+> See [Cursor Guide](./docs/guides/cursor.md) for detailed setup.
+
+### Other Editors (Manual)
+
+1. Run `invar init` → select "Other (AGENT.md)"
+2. Include generated `AGENT.md` in your agent's prompt
+3. Configure MCP server if supported
+4. Use CLI commands (`invar guard`) for verification
 
 ---
 
 ## 📂 What Gets Installed
 
-`invar init --claude` creates:
+`invar init` creates (select in interactive mode):
+
+| File/Directory | Purpose | Category |
+|----------------|---------|----------|
+| `INVAR.md` | Protocol for AI agents | Required |
+| `.invar/` | Config, context, examples | Required |
+| `.pre-commit-config.yaml` | Verification before commit | Optional |
+| `src/core/`, `src/shell/` | Recommended structure | Optional |
+| `CLAUDE.md` | Agent instructions | Claude Code |
+| `.claude/skills/` | Workflow automation | Claude Code |
+| `.claude/commands/` | User commands (/audit, /guard) | Claude Code |
+| `.claude/hooks/` | Tool guidance | Claude Code |
+| `.mcp.json` | MCP server config | Claude Code |
+| `AGENT.md` | Universal agent instructions | Other agents |
 
-| File/Directory | Purpose | Editable? |
-|----------------|---------|-----------|
-| `INVAR.md` | Protocol for AI agents | No (managed) |
-| `CLAUDE.md` | Project configuration | Yes |
-| `.claude/skills/` | Workflow skills | Yes |
-| `.claude/hooks/` | Tool call interception | Yes |
-| `.invar/examples/` | Reference patterns | No (managed) |
-| `.invar/context.md` | Project state, lessons | Yes |
-| `pyproject.toml` | `[tool.invar]` section | Yes |
+**Note:** If `pyproject.toml` exists, Guard configuration goes there as `[tool.invar.guard]` instead of `.invar/config.toml`.
 
 **Recommended structure:**
 
@@ -432,7 +454,9 @@ rules = ["missing_contract", "shell_result"]
 | `invar guard` | Full verification (static + doctest + property + symbolic) |
 | `invar guard --changed` | Only git-modified files |
 | `invar guard --static` | Static analysis only (~0.5s) |
-| `invar init` | Initialize or update project |
+| `invar init` | Initialize or update project (interactive) |
+| `invar init --claude` | Quick setup for Claude Code |
+| `invar uninstall` | Remove Invar from project (preserves user content) |
 | `invar sig <file>` | Show signatures and contracts |
 | `invar map` | Symbol map with reference counts |
 | `invar rules` | List all rules |

{invar_tools-1.7.0 → invar_tools-1.8.0}/docs/agents.md

@@ -345,8 +345,7 @@ Invar provides MCP (Model Context Protocol) tools for deeper integration with Cl
 ### Setup
 
 ```bash
-uvx invar-tools init    # Auto-creates .mcp.json at project root
-# or: invar init (if installed globally)
+uvx invar-tools init    # Interactive mode, auto-creates .mcp.json
 ```
 
 ### Available Tools

{invar_tools-1.7.0 → invar_tools-1.8.0}/docs/design.md

@@ -768,10 +768,11 @@ Create src/core and src/shell? [Y/n]
 **CLI Options:**
 
 ```bash
-invar init              # Interactive, asks about directories
-invar init --dirs       # Always create src/core, src/shell
-invar init --no-dirs    # Never create directories
-invar init --config-only # Only add config, no INVAR.md/CLAUDE.md
+invar init              # Interactive mode with menus
+invar init --claude     # Auto-select Claude Code, skip prompts
+invar init --preview    # Show what would be done (dry run)
+invar uninstall         # Remove Invar from project (preserves user content)
+invar uninstall --dry-run  # Preview what would be removed
 ```
 
 ---