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

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/config/pre-commit.yaml.jinja

@@ -1,3 +1,4 @@
+# invar:begin
 # Invar Pre-commit Hooks v{{ version }}
 # Install: pre-commit install
 #
@@ -42,3 +43,4 @@ repos:
         pass_filenames: false
         stages: [pre-commit]
         types: [python]
+# invar:end

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.0.dist-info → invar_tools-1.8.0.dist-info}/METADATA

@@ -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 |