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

invar/templates/INVAR.md

@@ -5,8 +5,14 @@
   │ This file is managed by Invar. Changes may be lost on       │
   │ `invar update`. Add project content to CLAUDE.md instead.   │
   └─────────────────────────────────────────────────────────────┘
+
+  License: CC-BY-4.0 (Creative Commons Attribution 4.0 International)
+  https://creativecommons.org/licenses/by/4.0/
+
+  You are free to share and adapt this document, provided you give
+  appropriate credit to the Invar project.
 -->
-# The Invar Protocol v3.26
+# The Invar Protocol v4.0
 
 > **"Trade structure for safety."**
 
@@ -70,46 +76,113 @@ def read_config(path: Path) -> Result[dict, str]:
 
 More examples: `.invar/examples/`
 
-## Session Start (Required)
+## Check-In (Required)
+
+Your first message MUST display:
+
+```
+✓ Check-In: guard PASS | top: <entry1>, <entry2>
+```
+
+Execute `invar_guard(changed=true)` and `invar_map(top=10)`, then show this one-line summary.
+
+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.
 
-Before writing any code, execute:
+## USBV Workflow (DX-32)
 
-1. **invar_guard** (changed=true) — Check existing violations
-2. **invar_map** (top=10) — Understand code structure
+**U**nderstand → **S**pecify → **B**uild → **V**alidate
 
-Then read:
-- `.invar/examples/` — Core/Shell patterns
-- `.invar/context.md` — Project state, lessons learned
+| Phase | Purpose | Activities |
+|-------|---------|------------|
+| UNDERSTAND | Know what and why | Intent, Inspect (invar sig/map), Constraints |
+| SPECIFY | Define boundaries | @pre/@post, Design decomposition, Doctests |
+| BUILD | Write code | Implement leaves, Compose |
+| VALIDATE | Confirm correctness | invar guard, Review Gate, Reflect |
 
-**Skipping these steps → Non-compliant code → Rework required.**
+**Key:** Inspect before Contract. Depth varies naturally. Iterate when needed.
 
-Use MCP tools if available (`invar_guard`, `invar_map`), otherwise use CLI commands.
-For agent-specific entry format, see your configuration file (CLAUDE.md, .cursorrules, etc).
+**Review Gate:** When Guard triggers `review_suggested` (escape hatches ≥3, security paths, low coverage), invoke `/review` before completion.
 
-## ICIDIV Workflow (Required Order)
+## Visible Workflow (DX-30)
+
+For complex tasks (3+ functions), show 3 checkpoints in TodoList:
 
 ```
-1. Intent    — What? Core or Shell? Edge cases?
-2. Contract  — @pre/@post + doctests BEFORE code
-3. Inspect   — invar sig <file>, invar map --top 10
-4. Design    — Decompose: leaves first, then compose
-5. Implement — Write code to pass your doctests
-6. Verify    — invar guard. If fail: reflect → fix → verify
+□ [UNDERSTAND] Task description, codebase context, constraints
+□ [SPECIFY] Contracts (@pre/@post) and design decomposition
+□ [VALIDATE] Guard results, Review Gate if triggered, integration status
 ```
 
-**Contract before Implement. Verify after every change. No exceptions.**
+**BUILD is internal work** — not shown in TodoList.
+
+**Show contracts before code.** Example:
+
+```python
+[SPECIFY] calculate_discount:
+@pre(lambda price, rate: price > 0 and 0 <= rate <= 1)
+@post(lambda result: result >= 0)
+def calculate_discount(price: float, rate: float) -> float: ...
+
+[BUILD] Now coding...
+```
+
+**When to use:** New features (3+ functions), architectural changes, Core modifications.
+**Skip for:** Single-line fixes, documentation, trivial refactoring.
 
 ## Task Completion
 
 A task is complete only when ALL conditions are met:
-- Session Start executed (invar_guard + invar_map, context read)
+- Check-In displayed: `✓ Check-In: guard PASS | top: <entry1>, <entry2>`
 - Intent explicitly stated
 - Contract written before implementation
-- Final **invar_guard** passed
+- Final displayed: `✓ Final: guard PASS | <errors>, <warnings>`
 - User requirement satisfied
 
 **Missing any = Task incomplete.**
 
+## Markers
+
+### Entry Points
+
+Entry points are framework callbacks (`@app.route`, `@app.command`) at Shell boundary.
+- **Exempt** from `Result[T, E]` — must match framework signature
+- **Keep thin** (max 15 lines) — delegate to Shell functions that return Result
+
+Auto-detected by decorators. For custom callbacks:
+
+```python
+# @shell:entry
+def on_custom_event(data: dict) -> dict:
+    result = handle_event(data)
+    return result.unwrap_or({"error": "failed"})
+```
+
+### Shell Complexity
+
+When shell function complexity is justified:
+
+```python
+# @shell_complexity: Subprocess with error classification
+def run_external_tool(...): ...
+
+# @shell_orchestration: Multi-step pipeline coordination
+def process_batch(...): ...
+```
+
+### Architecture Escape Hatch
+
+When rule violation has valid architectural justification:
+
+```python
+# @invar:allow shell_result: Framework callback signature fixed
+def flask_handler(): ...
+```
+
+See `invar rules` for all rule names.
+
 ## Commands
 
 ```bash
@@ -126,9 +199,9 @@ invar map --top 10       # Most-referenced symbols
 [tool.invar.guard]
 core_paths = ["src/myapp/core"]
 shell_paths = ["src/myapp/shell"]
-exclude_doctest_lines = true  # Don't count doctests in function size
+# DX-22: Doctest lines are always excluded from size calculations by default
 ```
 
 ---
 
-*Protocol v3.26 | [Guide](docs/INVAR-GUIDE.md) | [Examples](.invar/examples/)*
+*Protocol v4.0 — USBV workflow (DX-32) | [Guide](docs/INVAR-GUIDE.md) | [Examples](.invar/examples/)*

invar/templates/aider.conf.yml.template

@@ -4,26 +4,28 @@
 # Auto-read protocol files at session start
 read:
   - INVAR.md
-  - .invar/examples/core_example.py
-  - .invar/examples/shell_example.py
+  - .invar/examples/contracts.py
+  - .invar/examples/core_shell.py
   - .invar/context.md
 
 # System prompt addition
 system-prompt: |
   Follow the Invar Protocol in INVAR.md.
 
-  Before writing code, execute:
-  1. invar_guard (changed=true) - or: invar guard --changed
-  2. invar_map (top=10) - or: invar map --top 10
+  ## Check-In
+  Your first message MUST display:
+  ✓ Check-In: guard PASS | top: <entry1>, <entry2>
 
-  Use MCP tools if available, otherwise use CLI commands.
+  Execute: invar guard --changed && invar map --top 10
+  This is your sign-in. No visible check-in = Session not started.
 
-  Workflow (ICIDIV):
-  - Intent: What? Core or Shell?
-  - Contract: @pre/@post + doctests BEFORE code
-  - Inspect: invar_sig (or: invar sig <file>)
-  - Design: Decompose first
-  - Implement: Pass your doctests
-  - Verify: invar_guard (or: invar guard)
+  ## Final
+  Your last message MUST display:
+  ✓ Final: guard PASS | 0 errors, 2 warnings
 
-  Task complete only when final invar_guard passes.
+  Execute: invar guard
+  This is your sign-out. Completes the Check-In/Final pair.
+
+  ## Workflow (USBV)
+  Understand → Specify → Build → Validate
+  Inspect before Contract. Depth varies naturally.

invar/templates/commands/review.md

@@ -0,0 +1,200 @@
+# Code Review (Reviewer Role)
+
+## Mode Detection (Required First Step)
+
+Before reviewing, determine the appropriate mode:
+
+### Check for `review_suggested`
+
+Look at your conversation history for recent `invar guard` output, or run:
+```bash
+invar guard --changed
+```
+
+Check if `review_suggested` warning is present:
+```
+WARNING: review_suggested - High escape hatch count: N @invar:allow markers
+WARNING: review_suggested - Security-sensitive path detected
+WARNING: review_suggested - Low contract coverage
+```
+
+### Select Mode
+
+| Condition | Mode | Why |
+|-----------|------|-----|
+| `review_suggested` present | **Isolated** | Eliminates confirmation bias |
+| No trigger | **Quick** | Faster, context preserved |
+| User requests `--isolated` | **Isolated** | Explicit override |
+| User requests `--quick` | **Quick** | Explicit override |
+
+---
+
+## Isolated Mode
+
+**Use when:** `review_suggested` triggered, or user explicitly requests isolation.
+
+Spawn an independent reviewer with fresh context using Task tool:
+
+```
+I'll spawn an independent reviewer to eliminate confirmation bias...
+
+[Task tool call]
+prompt: |
+  You are an adversarial code reviewer. Your job is to FIND PROBLEMS.
+
+  Review these files: {files_to_review}
+
+  Read .claude/commands/review.md for the full checklist, then:
+  1. Check contract semantic value (not just syntax)
+  2. Audit all escape hatches (@invar:allow)
+  3. Look for logic errors and edge cases
+  4. Check security if applicable
+
+  Report issues as CRITICAL/MAJOR/MINOR with file:line locations.
+
+  Your success is measured by problems found, not code approved.
+
+subagent_type: "general-purpose"
+```
+
+After receiving the sub-agent's report, summarize findings for the user.
+
+**Key:** The sub-agent has NO conversation history. It only sees the code.
+
+---
+
+## Quick Mode
+
+**Use when:** No `review_suggested` trigger, routine review needed.
+
+Proceed with same-context review below.
+
+---
+
+## Adversarial Reviewer Persona
+
+You are an **adversarial code reviewer**. Your job is to FIND PROBLEMS.
+
+### Your Mindset
+
+Assume:
+- The code has bugs until proven otherwise
+- The contracts may be meaningless ceremony
+- The implementer may have rationalized poor decisions
+- Escape hatches may be abused
+
+You are NOT here to:
+- Validate that code works
+- Confirm the implementer did a good job
+- Be nice or diplomatic
+
+You ARE here to:
+- Find bugs, logic errors, edge cases
+- Challenge whether contracts have semantic value
+- Identify code smells and duplication
+- Question every escape hatch
+- Check if code matches contracts (not if code "seems right")
+
+**Your success is measured by problems found, not code approved.**
+
+---
+
+## Review Checklist
+
+> **Principle:** Only items requiring semantic judgment. Mechanical checks are excluded (see bottom).
+
+### A. Contract Semantic Value
+- [ ] Does @pre constrain inputs beyond type checking?
+  - Bad: `@pre(lambda x: isinstance(x, int))`
+  - Good: `@pre(lambda x: x > 0 and x < MAX_VALUE)`
+- [ ] Does @post verify meaningful output properties?
+  - Bad: `@post(lambda result: result is not None)`
+  - Good: `@post(lambda result: len(result) == len(input))`
+- [ ] Could someone implement correctly from contracts alone?
+- [ ] Are boundary conditions explicit in contracts?
+
+### B. Doctest Coverage
+- [ ] Do doctests cover normal cases?
+- [ ] Do doctests cover boundary cases?
+- [ ] Do doctests cover error cases?
+- [ ] Are doctests testing behavior, not just syntax?
+
+### C. Code Quality
+- [ ] Is duplicated code worth extracting?
+- [ ] Is naming consistent and clear?
+- [ ] Is complexity justified?
+
+### D. Escape Hatch Audit
+- [ ] Is each @invar:allow justification valid?
+- [ ] Could refactoring eliminate the need?
+- [ ] Is there a pattern suggesting systematic issues?
+
+### E. Logic Verification
+- [ ] Do contracts correctly capture intended behavior?
+- [ ] Are there paths that bypass contract checks?
+- [ ] Are there implicit assumptions not in contracts?
+- [ ] What happens with unexpected inputs?
+
+### F. Security
+- [ ] Are inputs validated against security threats (injection, XSS)?
+- [ ] No hardcoded secrets (API keys, passwords, tokens)?
+- [ ] Are authentication/authorization checks correct?
+- [ ] Is sensitive data properly protected?
+
+### G. Error Handling & Observability
+- [ ] Are exceptions caught at appropriate level?
+- [ ] Are error messages clear without leaking sensitive info?
+- [ ] Are critical operations logged for debugging?
+- [ ] Is there graceful degradation on failure?
+
+---
+
+## Excluded (Covered by Tools)
+
+These are checked by Guard or linters - don't duplicate:
+- Core/Shell separation → Guard (forbidden_import, impure_call)
+- Shell returns Result[T,E] → Guard (shell_result)
+- Missing contracts → Guard (missing_contract)
+- File/function size limits → Guard (file_size, function_size)
+- Entry point thickness → Guard (entry_point_too_thick)
+- Magic numbers → Linters (ruff)
+- Escape hatch count → Guard (review_suggested)
+
+---
+
+## Report Format
+
+For each issue found, use severity levels:
+
+| Severity | Meaning | Enforcement |
+|----------|---------|-------------|
+| **CRITICAL** | Must fix before completion | Blocking |
+| **MAJOR** | Fix or provide written justification | Strong |
+| **MINOR** | Optional, can defer | Advisory |
+
+```markdown
+### [CRITICAL/MAJOR/MINOR] Issue Title
+
+**Location:** file.py:line_number
+**Category:** contract_quality | logic_error | security | escape_hatch | code_smell
+**Problem:** What's wrong
+**Suggestion:** How to fix (if applicable)
+```
+
+---
+
+## Instructions Summary
+
+1. **Mode Detection:** Check for `review_suggested` in guard output
+2. **If Isolated Mode:** Spawn Task sub-agent (fresh context)
+3. **If Quick Mode:** Proceed with same-context adversarial review
+4. Go through each checklist category
+5. For each issue, determine severity (CRITICAL/MAJOR/MINOR)
+6. Report with structured format above
+7. Be thorough and adversarial
+
+**Remember:** You are READ-ONLY. Report issues, don't fix them directly.
+
+---
+
+Now review the recent changes or the files specified by the user.

invar/templates/cursorrules.template

@@ -1,28 +1,37 @@
 # Invar Protocol
 
-Follow the Invar Protocol in INVAR.md — includes Session Start, ICIDIV workflow, and Task Completion requirements.
+Follow the Invar Protocol in INVAR.md — includes Check-In, USBV workflow, and Task Completion requirements.
 
-## Cursor-Specific: Entry Verification
+## Check-In
 
-Before writing any code, execute and show output from:
+Your first message MUST display:
 
 ```
-invar_guard (changed=true)   # Check existing violations
-invar_map (top=10)           # Understand code structure
+✓ Check-In: guard PASS | top: <entry1>, <entry2>
 ```
 
-Use MCP tools if available, otherwise use CLI commands:
-- `invar guard --changed`
-- `invar map --top 10`
+Execute `invar guard --changed` and `invar map --top 10`, then show this one-line summary.
 
-Then read .invar/examples/ and .invar/context.md.
+This is your sign-in. The user sees it immediately.
+No visible check-in = Session not started.
 
-Skipping these steps leads to non-compliant code.
+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.
 
 ## Quick Reference
 
 - Core (`**/core/**`): @pre/@post contracts, doctests, pure (no I/O)
 - Shell (`**/shell/**`): Result[T, E] return type
-- Workflow: Intent → Contract → Inspect → Design → Implement → Verify
-- Contract before Implement. No exceptions.
-- Task complete only when final invar_guard passes.
+- Workflow: Understand → Specify → Build → Validate (USBV)
+- Inspect before Contract. Depth varies naturally.

invar/templates/examples/contracts.py

@@ -5,7 +5,9 @@ Reference patterns for @pre/@post contracts and doctests.
 Managed by Invar - do not edit directly.
 """
 
-from deal import post, pre
+# Use invar_runtime for lightweight runtime contracts
+# (or 'from deal import pre, post' works too - deal is the underlying library)
+from invar_runtime import post, pre
 
 # =============================================================================
 # GOOD: Complete Contract

invar/templates/examples/core_shell.py

@@ -7,7 +7,9 @@ Managed by Invar - do not edit directly.
 
 from pathlib import Path
 
-from deal import post, pre
+# Use invar_runtime for lightweight runtime contracts
+# (or 'from deal import pre, post' works too - deal is the underlying library)
+from invar_runtime import post, pre
 from returns.result import Failure, Result, Success
 
 # =============================================================================

{invar_tools-1.0.0.dist-info → invar_tools-1.2.0.dist-info}/METADATA

@@ -1,18 +1,20 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.0.0
+Version: 1.2.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
 Project-URL: Repository, https://github.com/tefx/invar
 Project-URL: Issues, https://github.com/tefx/invar/issues
 Author: Invar Team
-License-Expression: MIT
+License-Expression: GPL-3.0-or-later
 License-File: LICENSE
+License-File: LICENSE-GPL
+License-File: NOTICE
 Keywords: ai,code-quality,contracts,design-by-contract,static-analysis
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -39,7 +41,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI version](https://badge.fury.io/py/invar-tools.svg)](https://badge.fury.io/py/invar-tools)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License](https://img.shields.io/badge/License-Apache%202.0%20%2B%20GPL--3.0-blue.svg)](#license)
 
 **Don't hope AI code is correct. Know it.**
 
@@ -62,39 +64,74 @@ def average(items: list[float]) -> float:
 
 ## Installation
 
-### Development Tools
+### Two Packages, Different Purposes
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Your Project                                                   │
+│  ├── src/                                                       │
+│  │   └── from invar_runtime import pre, post  ← Runtime        │
+│  │                                                              │
+│  └── Development (not shipped with your code)                   │
+│      └── uvx invar-tools guard  ← Tools                         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+| Package | Install | When to Use |
+|---------|---------|-------------|
+| **invar-tools** | `uvx invar-tools <cmd>` | Development: verification, init, MCP server |
+| **invar-runtime** | `pip install invar-runtime` | Production: add to your project's dependencies |
+
+### Development Tools (invar-tools)
 
 ```bash
-# Recommended: use without installing
+# Recommended: use without installing (always latest, isolated)
 uvx invar-tools guard
+uvx invar-tools init --claude
+uvx invar-tools map --top 10
 
 # Or install globally
 pip install invar-tools
+invar guard
 ```
 
-### Runtime Contracts (for your project)
+### Runtime Contracts (invar-runtime)
+
+Add to your project's `requirements.txt` or `pyproject.toml`:
 
 ```bash
 pip install invar-runtime
 ```
 
-**Packages:**
+```python
+# In your code
+from invar_runtime import pre, post
 
-| Package | Size | Purpose |
-|---------|------|---------|
-| `invar-runtime` | ~3MB | Runtime contracts (`@pre`, `@post`, etc.) |
-| `invar-tools` | ~100MB | Development tools (`guard`, `map`, `sig`, MCP) |
+@pre(lambda x: x > 0)
+@post(lambda result: result >= 0)
+def calculate(x: float) -> float:
+    ...
+```
 
 ---
 
 ## Quick Start
 
 ```bash
+# 1. Initialize your project (no install required!)
 cd your-project
-invar init          # Creates INVAR.md, CLAUDE.md, .invar/
-invar guard         # Verify code quality
+uvx invar-tools init --claude    # Creates INVAR.md, CLAUDE.md, configures MCP
+
+# 2. Write code with AI (AI follows INVAR.md protocol)
+
+# 3. Verify code quality
+uvx invar-tools guard            # Runs static analysis + doctests
 ```
 
+> **Why uvx?** No global install needed. Always uses latest version. Isolated environment.
+>
+> Alternative: `pip install invar-tools` then use `invar` instead of `uvx invar-tools`
+
 **Multi-Agent Support:** `invar init` auto-detects and configures:
 
 | AI Tool | Configuration |
@@ -266,6 +303,25 @@ Manual setup: See `.invar/mcp-setup.md` after running `invar init`.
 
 ---
 
+## Platform Support (DX-31)
+
+The Independent Adversarial Reviewer (DX-31) has different capabilities depending on your AI coding assistant:
+
+| Feature | Claude Code | Other Agents |
+|---------|-------------|--------------|
+| Guard `review_suggested` | ✅ | ✅ |
+| Automatic sub-agent review | ✅ Task tool | ❌ Manual action |
+| Context isolation | ✅ Fresh context | N/A |
+| Adversarial mindset | ✅ Prompt-based | User responsibility |
+
+**Claude Code:** Full independent review with context isolation. When Guard outputs `review_suggested`, the agent automatically spawns a sub-agent reviewer that sees only the code (not the implementation history).
+
+**Cursor, Windsurf, Copilot, etc.:** Guard outputs `review_suggested` as a warning. Users must manually invoke review or use external code review tools.
+
+**Why context isolation matters:** The same agent that wrote code has "author blindness" — it remembers its rationale and unconsciously validates its own decisions. An isolated reviewer sees only the code.
+
+---
+
 ## File Ownership
 
 | File | Owner | Edit? |
@@ -318,4 +374,14 @@ DEAL_DISABLE=1 python app.py
 
 ## License
 
-MIT
+This project uses a dual-license structure:
+
+| Component | License | Purpose |
+|-----------|---------|---------|
+| **invar-runtime** | [Apache-2.0](LICENSE) | Runtime contracts - use freely in your projects |
+| **invar-tools** | [GPL-3.0](LICENSE-GPL) | CLI tools - ensures improvements are shared |
+| **Documentation** | [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) | Protocol docs - share with attribution |
+
+**For users:** You can use `invar-runtime` in any project (including proprietary). The `invar-tools` CLI is for development only and doesn't affect your project's license.
+
+See [NOTICE](NOTICE) for third-party licenses.