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

invar/templates/config/pre-commit.yaml.jinja

@@ -0,0 +1,44 @@
+# Invar Pre-commit Hooks v{{ version }}
+# Install: pre-commit install
+#
+# Default runs full verification (static + doctests + CrossHair + Hypothesis).
+# Incremental mode makes this fast: ~5s first commit, ~2s subsequent (cached).
+#
+# Smart Guard: Detects rule-affecting file changes and runs full guard when needed.
+# Structure Protection: Warns if INVAR.md is modified directly.
+
+repos:
+  - repo: local
+    hooks:
+      # Warn if INVAR.md is modified directly (use --no-verify if intentional)
+      - id: invar-md-protected
+        name: INVAR.md Protection
+        entry: bash -c 'if git diff --cached --name-only | grep -q "^INVAR.md$"; then echo "Warning - INVAR.md was modified directly. Use git commit --no-verify if intentional."; exit 1; fi'
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+
+      # Invar Guard (full verification by default)
+      # Uses incremental mode: only verifies changed files, caches results
+      # Smart mode: runs full guard when rule files change, --changed otherwise
+      - id: invar-guard
+        name: Invar Guard
+        entry: bash -c '
+          RULE_FILES="rule_meta.py rules.py contracts.py purity.py pyproject.toml"
+          STAGED=$(git diff --cached --name-only)
+          FULL=false
+          for f in $RULE_FILES; do
+            if echo "$STAGED" | grep -q "$f"; then FULL=true; break; fi
+          done
+          if [ "$FULL" = true ]; then
+            echo "⚠️  Rule change detected - running FULL guard"
+            invar guard
+          else
+            invar guard --changed
+          fi
+        '
+        language: python
+        additional_dependencies: ['invar-tools']
+        pass_filenames: false
+        stages: [pre-commit]
+        types: [python]

invar/templates/context.md.template

@@ -8,6 +8,39 @@
 - Working on: [current task or feature]
 - Blockers: None
 
+## Key Rules (Quick Reference)
+
+<!-- DX-54: Rules summary for long conversation resilience -->
+
+### Core/Shell Separation
+- **Core** (`**/core/**`): @pre/@post + doctests, NO I/O imports
+- **Shell** (`**/shell/**`): Result[T, E] return type
+
+### USBV Workflow
+1. Understand → 2. Specify (contracts first) → 3. Build → 4. Validate
+
+### Verification
+- `invar guard` = static + doctests + CrossHair + Hypothesis
+- Final must show: `✓ Final: guard PASS | ...`
+
+## Self-Reminder
+
+<!-- DX-54: AI should re-read this file periodically -->
+
+**When to re-read this file:**
+- Starting a new task
+- Completing a task (before moving to next)
+- Conversation has been going on for a while (~15-20 exchanges)
+- Unsure about project rules or patterns
+
+**Quick rule check:**
+- Am I in Core or Shell?
+- Do I have @pre/@post contracts?
+- Am I following USBV workflow?
+- Did I run guard before claiming "done"?
+
+---
+
 ## Recent Decisions
 
 1. [Decision summary] - [Brief rationale]

invar/templates/cursorrules.template

@@ -1,28 +1,40 @@
 # 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: [project] | [branch] | [clean/dirty]
 ```
 
-Use MCP tools if available, otherwise use CLI commands:
-- `invar guard --changed`
-- `invar map --top 10`
+Actions:
+1. Read `.invar/context.md` (Key Rules + Current State + Lessons Learned)
+2. Show one-line status
 
-Then read .invar/examples/ and .invar/context.md.
+**Do NOT execute guard or map at Check-In.**
+Guard is for VALIDATE phase and Final only.
 
-Skipping these steps leads to non-compliant code.
+This is your sign-in. The user sees it immediately.
+No visible check-in = Session not started.
+
+## 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/README.md

@@ -8,6 +8,7 @@ Reference examples for the Invar Protocol. These are managed by Invar.
 |------|---------|
 | [contracts.py](contracts.py) | @pre/@post patterns, doctest best practices |
 | [core_shell.py](core_shell.py) | Core/Shell separation patterns |
+| [workflow.md](workflow.md) | Visible USBV workflow example |
 
 ## Usage
 
@@ -15,6 +16,7 @@ Read these when you need:
 - Contract pattern reference
 - Core vs Shell decision guidance
 - Doctest formatting examples
+- USBV workflow example
 
 ---
 

invar/templates/examples/conftest.py

@@ -0,0 +1,3 @@
+# Skip pytest collection for example files
+# These are reference examples, not tests.
+collect_ignore = ["contracts.py", "core_shell.py", "workflow.md"]

invar/templates/examples/contracts.py

@@ -5,6 +5,8 @@ Reference patterns for @pre/@post contracts and doctests.
 Managed by Invar - do not edit directly.
 """
 
+# For lambda-based contracts, use deal directly
+# invar_runtime.pre/post are for Contract objects (NonEmpty, IsInstance, etc.)
 from deal import post, pre
 
 # =============================================================================
@@ -54,8 +56,8 @@ def average(items: list[float]) -> float:
 # =============================================================================
 
 
-@pre(lambda data: isinstance(data, dict))
-@post(lambda result: isinstance(result, dict))
+@pre(lambda data: len(data) > 0)  # Non-empty input (type is in annotation)
+@post(lambda result: len(result) > 0)  # Preserves non-emptiness
 def normalize_keys(data: dict[str, int]) -> dict[str, int]:
     """
     Lowercase all keys.

invar/templates/examples/core_shell.py

@@ -7,6 +7,8 @@ Managed by Invar - do not edit directly.
 
 from pathlib import Path
 
+# For lambda-based contracts, use deal directly
+# invar_runtime.pre/post are for Contract objects (NonEmpty, IsInstance, etc.)
 from deal import post, pre
 from returns.result import Failure, Result, Success
 
@@ -18,8 +20,10 @@ from returns.result import Failure, Result, Success
 # =============================================================================
 
 
-@pre(lambda content: isinstance(content, str))
-@post(lambda result: isinstance(result, list))
+# @invar:allow shell_result: Example file - demonstrates Core pattern
+# @shell_orchestration: Example file - demonstrates Core pattern
+@pre(lambda content: content is not None)  # Accepts any string including empty
+@post(lambda result: all(line.strip() == line and line for line in result))  # No whitespace, non-empty
 def parse_lines(content: str) -> list[str]:
     """
     Parse content into non-empty lines.
@@ -34,8 +38,10 @@ def parse_lines(content: str) -> list[str]:
     return [line.strip() for line in content.split("\n") if line.strip()]
 
 
-@pre(lambda items: isinstance(items, list))
-@post(lambda result: isinstance(result, dict))
+# @invar:allow shell_result: Example file - demonstrates Core pattern
+# @shell_orchestration: Example file - demonstrates Core pattern
+@pre(lambda items: all(isinstance(i, str) for i in items))  # All items must be strings
+@post(lambda result: all(v > 0 for v in result.values()))  # All counts are positive
 def count_items(items: list[str]) -> dict[str, int]:
     """
     Count occurrences of each item.

invar/templates/examples/workflow.md

@@ -0,0 +1,81 @@
+# Visible Workflow Example
+
+Complete example of USBV workflow with checkpoints for complex tasks.
+
+## Scenario
+
+User: "Add rate limiting to the API endpoints"
+
+## Workflow Execution
+
+```
+Agent: "Entering /develop for: Add rate limiting to API endpoints
+
+✓ Check-In: MyApp | feature/rate-limit | clean
+
+□ [UNDERSTAND]
+  - Task: Add rate limiting to API endpoints
+  - Scope: All routes in src/myapp/shell/api.py
+  - Constraint: Must be configurable per-route
+  - Existing: No rate limiting currently
+
+□ [SPECIFY] RateLimiter class (Core)
+  @pre(lambda max_requests, window_seconds: max_requests > 0 and window_seconds > 0)
+  @post(lambda result: result is not None)
+  def is_allowed(self, key: str) -> bool:
+      '''
+      >>> limiter = RateLimiter(max_requests=2, window_seconds=60)
+      >>> limiter.is_allowed('user1')
+      True
+      >>> limiter.is_allowed('user1')
+      True
+      >>> limiter.is_allowed('user1')  # 3rd request
+      False
+      '''
+      ...
+
+□ [SPECIFY] rate_limit decorator (Shell)
+  def rate_limit(max_requests: int, window_seconds: int):
+      '''Decorator for Flask routes. Returns Result[Response, RateLimitError].'''
+      ...
+
+[BUILD - implementing RateLimiter...]
+[BUILD - implementing decorator...]
+[BUILD - applying to routes...]
+
+□ [VALIDATE]
+  - Guard: PASS (0 errors, 0 warnings)
+  - Tests: All passing
+  - Integration: Manual test with curl
+
+✓ Final: guard PASS | 0 errors, 0 warnings
+
+Development complete. Added rate limiting:
+- Created: src/myapp/core/rate_limiter.py
+- Modified: src/myapp/shell/api.py (decorator applied)
+- Config: RATE_LIMIT_REQUESTS, RATE_LIMIT_WINDOW in .env"
+```
+
+## Key Points
+
+1. **Check-In first** - Shows project, branch, git status (no guard/map here)
+2. **UNDERSTAND visible** - Task scope and constraints clear
+3. **SPECIFY visible** - Contracts shown BEFORE implementation
+4. **BUILD hidden** - Internal work, not in checkpoints
+5. **VALIDATE visible** - Guard results and integration status
+6. **Final last** - Runs guard and completes the session
+
+## When to Use
+
+| Complexity | Use Visible Workflow? |
+|------------|----------------------|
+| 3+ functions | Yes |
+| Architectural changes | Yes |
+| New Core module | Yes |
+| Single-line fix | No |
+| Documentation only | No |
+| Trivial refactoring | No |
+
+---
+
+*Example for the Invar Protocol v5.0*

invar/templates/manifest.toml

@@ -0,0 +1,137 @@
+# DX-49: Template Manifest
+# Defines ownership rules and template behaviors
+
+[meta]
+version = "5.0"
+workflow = "USBV"
+
+# =============================================================================
+# Ownership Classification
+# =============================================================================
+
+[ownership]
+# Fully managed - safe to overwrite completely
+fully_managed = [
+    "INVAR.md",
+    ".invar/examples/**",
+]
+
+# Partially managed - only update marked regions
+partially_managed = [
+    "CLAUDE.md",
+    ".claude/skills/*/SKILL.md",
+    ".claude/commands/*.md",
+]
+
+# Never touch - other tools or user private files
+never_touch = [
+    ".claude/settings*.json",
+    ".mcp.json",
+    ".cursorrules",
+    ".aider*",
+]
+
+# =============================================================================
+# Region Definitions
+# =============================================================================
+
+[regions."CLAUDE.md"]
+managed = { action = "overwrite" }
+project = { action = "inject", source = ".invar/project-additions.md" }
+user = { action = "preserve" }
+
+[regions.".claude/skills/*/SKILL.md"]
+skill = { action = "overwrite" }
+extensions = { action = "preserve" }
+
+# =============================================================================
+# Template Generation
+# =============================================================================
+
+[templates]
+# Protocol files (direct copy)
+"INVAR.md" = { src = "protocol/INVAR.md", type = "copy" }
+
+# Config files (Jinja2 templates)
+"CLAUDE.md" = { src = "config/CLAUDE.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" }
+
+# Skills (Jinja2 with syntax variable)
+".claude/skills/develop/SKILL.md" = { src = "skills/develop/SKILL.md.jinja", type = "jinja" }
+".claude/skills/investigate/SKILL.md" = { src = "skills/investigate/SKILL.md.jinja", type = "jinja" }
+".claude/skills/propose/SKILL.md" = { src = "skills/propose/SKILL.md.jinja", type = "jinja" }
+".claude/skills/review/SKILL.md" = { src = "skills/review/SKILL.md.jinja", type = "jinja" }
+
+# Commands (direct copy)
+".claude/commands/audit.md" = { src = "commands/audit.md", type = "copy" }
+".claude/commands/guard.md" = { src = "commands/guard.md", type = "copy" }
+
+# Examples (directory copy)
+".invar/examples/" = { src = "examples/", type = "copy_dir" }
+
+# =============================================================================
+# Variables
+# =============================================================================
+
+[variables]
+# Available for Jinja2 templates
+syntax = "cli"          # "cli" or "mcp"
+version = "5.0"
+project_name = ""       # Set by init
+
+# =============================================================================
+# Command Behaviors
+# =============================================================================
+
+[commands.init]
+# Files created by invar init
+creates = [
+    "INVAR.md",
+    "CLAUDE.md",
+    ".invar/context.md",
+    ".invar/examples/",
+    ".claude/skills/",
+    ".claude/commands/",
+    ".pre-commit-config.yaml",
+]
+syntax = "cli"          # Default syntax for new projects
+
+[commands.update]
+# How invar update handles existing files
+overwrite = ["INVAR.md", ".invar/examples/"]
+merge = ["CLAUDE.md", ".claude/skills/"]
+skip = [".invar/context.md"]
+
+[commands.sync_self]
+# For Invar project only
+syntax = "mcp"
+inject_project_additions = true
+
+# =============================================================================
+# DX-56: Sync Configuration (Unified Sync Engine)
+# =============================================================================
+
+[sync]
+# Files that are fully managed (overwrite completely on sync)
+fully_managed = [
+    "INVAR.md",
+]
+
+# Files with region-based updates (update managed, preserve user)
+region_managed = [
+    "CLAUDE.md",
+    ".claude/skills/develop/SKILL.md",
+    ".claude/skills/investigate/SKILL.md",
+    ".claude/skills/propose/SKILL.md",
+    ".claude/skills/review/SKILL.md",
+]
+
+# Files created once, never updated by sync
+create_only = [
+    ".invar/context.md",
+    ".invar/examples/",
+    ".pre-commit-config.yaml",
+    ".claude/commands/audit.md",
+    ".claude/commands/guard.md",
+]

invar/templates/protocol/INVAR.md

@@ -0,0 +1,210 @@
+<!--
+  ┌─────────────────────────────────────────────────────────────┐
+  │ INVAR-MANAGED FILE - DO NOT EDIT DIRECTLY                   │
+  │                                                             │
+  │ 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 v5.0
+
+> **"Trade structure for safety."**
+
+## Six Laws
+
+| Law | Principle |
+|-----|-----------|
+| 1. Separation | Core (pure logic) / Shell (I/O) physically separate |
+| 2. Contract Complete | @pre/@post + doctests uniquely determine implementation |
+| 3. Context Economy | map → sig → code (only read what's needed) |
+| 4. Decompose First | Break into sub-functions before implementing |
+| 5. Verify Reflectively | Fail → Reflect (why?) → Fix → Verify |
+| 6. Integrate Fully | Local correct ≠ Global correct; verify all paths |
+
+## Core/Shell Architecture
+
+| Zone | Location | Requirements |
+|------|----------|--------------|
+| Core | `**/core/**` | @pre/@post, pure (no I/O), doctests |
+| Shell | `**/shell/**` | `Result[T, E]` return type |
+
+**Forbidden in Core:** `os`, `sys`, `subprocess`, `pathlib`, `open`, `requests`, `datetime.now`
+
+## Core Example (Pure Logic)
+
+```python
+from deal import pre, post
+
+@pre(lambda price, discount: price > 0 and 0 <= discount <= 1)
+@post(lambda result: result >= 0)
+def discounted_price(price: float, discount: float) -> float:
+    """
+    >>> discounted_price(100, 0.2)
+    80.0
+    >>> discounted_price(100, 0)      # Edge: no discount
+    100.0
+    """
+    return price * (1 - discount)
+```
+
+**Self-test:** Can someone else write the exact same function from just @pre/@post + doctests?
+
+## Shell Example (I/O Operations)
+
+```python
+from pathlib import Path
+from returns.result import Result, Success, Failure
+
+def read_config(path: Path) -> Result[dict, str]:
+    """Shell: handles I/O, returns Result for error handling."""
+    try:
+        import json
+        return Success(json.loads(path.read_text()))
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except json.JSONDecodeError as e:
+        return Failure(f"Invalid JSON: {e}")
+```
+
+**Pattern:** Shell reads file → passes content to Core → returns Result.
+
+More examples: `.invar/examples/`
+
+## Check-In (Required)
+
+Your first message MUST display:
+
+```
+✓ Check-In: [project] | [branch] | [clean/dirty]
+```
+
+Actions:
+1. Read `.invar/context.md` (Key Rules + Current State + Lessons Learned)
+2. Show one-line status
+
+**Do NOT execute guard or map at Check-In.**
+Guard is for VALIDATE phase and Final only.
+
+This is your sign-in. The user sees it immediately.
+No visible check-in = Session not started.
+
+## USBV Workflow (DX-32)
+
+**U**nderstand → **S**pecify → **B**uild → **V**alidate
+
+| 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 |
+
+**Key:** Inspect before Contract. Depth varies naturally. Iterate when needed.
+
+**Review Gate:** When Guard triggers `review_suggested` (escape hatches ≥3, security paths, low coverage), invoke `/review` before completion.
+
+## Visible Workflow (DX-30)
+
+For complex tasks (3+ functions), show 3 checkpoints in TodoList:
+
+```
+□ [UNDERSTAND] Task description, codebase context, constraints
+□ [SPECIFY] Contracts (@pre/@post) and design decomposition
+□ [VALIDATE] Guard results, Review Gate if triggered, integration status
+```
+
+**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:
+- 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.**
+
+## 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
+invar guard              # Full: static + doctests + CrossHair + Hypothesis (default)
+invar guard --static     # Static only (quick debug, ~0.5s)
+invar guard --changed    # Modified files only
+invar sig <file>         # Show contracts + signatures
+invar map --top 10       # Most-referenced symbols
+```
+
+## Configuration
+
+```toml
+[tool.invar.guard]
+core_paths = ["src/myapp/core"]
+shell_paths = ["src/myapp/shell"]
+# DX-22: Doctest lines are always excluded from size calculations by default
+```
+
+---
+
+*Protocol v5.0 — USBV workflow (DX-32) | [Guide](docs/guide.md) | [Examples](.invar/examples/)*