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

invar/templates/examples/core_shell.py

@@ -7,9 +7,9 @@ Managed by Invar - do not edit directly.
 
 from pathlib import Path
 
-# 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
+# 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
 
 # =============================================================================
@@ -20,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.
@@ -36,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/{INVAR.md → protocol/INVAR.md}

@@ -12,7 +12,7 @@
   You are free to share and adapt this document, provided you give
   appropriate credit to the Invar project.
 -->
-# The Invar Protocol v4.0
+# The Invar Protocol v5.0
 
 > **"Trade structure for safety."**
 
@@ -81,16 +81,19 @@ More examples: `.invar/examples/`
 Your first message MUST display:
 
 ```
-✓ Check-In: guard PASS | top: <entry1>, <entry2>
+✓ Check-In: [project] | [branch] | [clean/dirty]
 ```
 
-Execute `invar_guard(changed=true)` and `invar_map(top=10)`, then show this one-line summary.
+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.
 
-Then read `.invar/context.md` for project state and lessons learned.
-
 ## USBV Workflow (DX-32)
 
 **U**nderstand → **S**pecify → **B**uild → **V**alidate
@@ -135,7 +138,7 @@ def calculate_discount(price: float, rate: float) -> float: ...
 ## Task Completion
 
 A task is complete only when ALL conditions are met:
-- Check-In displayed: `✓ Check-In: guard PASS | top: <entry1>, <entry2>`
+- Check-In displayed: `✓ Check-In: [project] | [branch] | [clean/dirty]`
 - Intent explicitly stated
 - Contract written before implementation
 - Final displayed: `✓ Final: guard PASS | <errors>, <warnings>`
@@ -204,4 +207,4 @@ shell_paths = ["src/myapp/shell"]
 
 ---
 
-*Protocol v4.0 — USBV workflow (DX-32) | [Guide](docs/INVAR-GUIDE.md) | [Examples](.invar/examples/)*
+*Protocol v5.0 — USBV workflow (DX-32) | [Guide](docs/guide.md) | [Examples](.invar/examples/)*

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

@@ -0,0 +1,318 @@
+<!--invar:skill version="{{ version }}"-->
+<!-- ========================================================================
+     SKILL REGION - DO NOT EDIT
+     This section is managed by Invar and will be overwritten on update.
+     To add project-specific extensions, use the "extensions" region below.
+     ======================================================================== -->
+---
+name: develop
+description: Implementation phase following USBV workflow. Use when task is clear and actionable - "add", "implement", "create", "fix", "update", "build", "write". Requires Check-In at start and Final at end.
+---
+
+# Development Mode
+
+> **Purpose:** Implement solution following USBV workflow with verification.
+
+## Entry Actions (REQUIRED)
+
+### Context Refresh (DX-54)
+
+Before any workflow action:
+1. Read `.invar/context.md` (especially Key Rules section)
+2. Display routing announcement
+
+### Routing Announcement
+
+```
+📍 Routing: /develop — [trigger detected, e.g. "add", "fix", "implement"]
+   Task: [user's request summary]
+```
+
+### Simple Task Detection
+
+If task appears simple (4+ signals: single file, clear target, additive change, <50 lines):
+
+```
+📊 Simple task (1 file, ~N lines).
+   Auto-orchestrate: investigate → develop → validate?
+   [Y/N]
+```
+
+- Y → Execute full cycle without intermediate confirmations
+- N → Proceed with normal USBV checkpoints
+- No response → Default to step-by-step (safe)
+
+## USBV Workflow
+
+### 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
+
+**For complex tasks:** Enter Plan Mode first, get user approval.
+
+**Implementation rules:**
+- 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
+
+**Commit format:**
+```bash
+git add . && git commit -m "feat: [description]
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+### 4. VALIDATE
+
+{% if syntax == "mcp" -%}
+- Run `invar_guard()` (full verification)
+{% else -%}
+- Run `invar guard` (full verification)
+{% endif -%}
+- All TodoWrite items complete
+- Integration works (if applicable)
+
+## Task Batching
+
+For multiple tasks:
+1. Create TodoWrite with all items upfront
+2. Execute sequentially (not parallel)
+3. After each task:
+   - Commit changes
+{% if syntax == "mcp" -%}
+   - Run `invar_guard(changed=true)`
+{% else -%}
+   - Run `invar guard --changed`
+{% endif -%}
+   - Update TodoWrite
+4. **Limits:** Max 5 tasks OR 4 hours OR Guard failure
+
+## Failure Handling
+
+| Guard Result | Action |
+|--------------|--------|
+| Static fixable (missing contract) | Auto-fix, retry (max 2) |
+| Test failure | Report to user, ask for guidance |
+| Contract violation | Report, suggest `/investigate` |
+| Repeated failure | Stop, ask user |
+
+## Common Guard Errors
+
+Quick reference for resolving common Guard errors:
+
+| Error | Cause | Quick Fix |
+|-------|-------|-----------|
+| `forbidden_import: io` | I/O library in Core | Use `iter(s.splitlines())` not `io.StringIO` |
+| `forbidden_import: os` | os module in Core | Accept `Path` as parameter instead |
+| `forbidden_import: pathlib` | pathlib in Core | Accept `Path` or `str` as parameter |
+| `internal_import` | Import inside function | Move import to module top |
+| `missing_contract` | Core function without @pre/@post | Add contract before implementation |
+| `empty_contract` | Contract with no condition | Add meaningful condition |
+| `redundant_type_contract` | Contract only checks types | Add semantic constraints (bounds, relationships) |
+| `partial_contract` | Only some params validated | Validate all params or document why partial |
+| `file_size` | File > 500 lines | Extract functions to new module |
+| `shell_result` | Shell function missing Result | Return `Result[T, E]` from `returns` |
+
+**Tip:** For `missing_contract`, Guard automatically suggests contracts based on parameter types.
+Check the "Suggested:" line in Guard output.
+
+**Note:** Use `from deal import pre, post` for lambda-based contracts.
+`invar_runtime.pre/post` are for Contract objects like `NonEmpty`.
+
+## Timeout Handling
+
+| Threshold | Duration | Action |
+|-----------|----------|--------|
+| Warning | 3 hours (75%) | Soft warning with options |
+| Hard stop | 4 hours (max) | Save state, exit |
+
+**75% Warning:**
+```
+⏱ Time check: /develop has been running for 3 hours.
+   Remaining estimate: [based on TodoWrite progress]
+
+   Options:
+   A: Continue (1 hour max remaining)
+   B: Wrap up current task and exit
+   C: Checkpoint and pause for later
+
+   Choice? (auto-continue in 2 minutes if no response)
+```
+
+**Hard Stop:**
+```
+⏱ /develop reached 4-hour limit.
+
+   Completed: [N]/[M] tasks
+   Current task: [description] - [%] complete
+
+   Saving state for resume. Run '/develop --resume' to continue.
+```
+
+## Exit Actions (REQUIRED)
+
+### Final
+
+{% if syntax == "mcp" -%}
+```python
+invar_guard()
+```
+{% else -%}
+```bash
+invar guard
+```
+{% endif %}
+
+**Display:**
+```
+✓ Final: guard [PASS/FAIL] | [errors] errors, [warnings] warnings
+```
+
+### Auto-Review (DX-41)
+
+If Guard outputs `review_suggested`:
+
+```
+⚠ review_suggested: [reason]
+
+📍 Routing: /review — review_suggested triggered
+   Task: Review [N files changed]
+```
+
+Proceed directly to /review skill. User can say "skip" to bypass.
+
+## Phase Visibility (DX-51)
+
+**USBV phases must be visually distinct.** On each phase transition, display a phase header:
+
+### Phase Header Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → SPECIFY (2/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Compact Format (brief updates)
+
+```
+📍 VALIDATE — Running guard...
+```
+
+### Three-Layer Visibility
+
+| Layer | What | Tool |
+|-------|------|------|
+| Skill | `/develop` | Routing announcement |
+| Phase | `SPECIFY (2/4)` | Phase header (this section) |
+| Tasks | Concrete items | TodoWrite |
+
+**Phase headers are SEPARATE from TodoWrite.**
+- Phase = where you are in workflow (visible in output)
+- TodoWrite = what tasks need doing (visible in status panel)
+
+**BUILD is internal work** — show header but no detailed breakdown.
+
+## Tool Selection
+
+| I want to... | Use |
+|--------------|-----|
+{% if syntax == "mcp" -%}
+| See contracts | `invar_sig <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 -%}
+| Edit symbol | Serena `replace_symbol_body` |
+| Add after symbol | Serena `insert_after_symbol` |
+| Rename symbol | Serena `rename_symbol` |
+
+## Example
+
+```
+User: "Add input validation to parse_source"
+
+Agent:
+📍 Routing: /develop — "add" trigger detected
+   Task: Add input validation to parse_source
+
+✓ Check-In: Invar | main | clean
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → UNDERSTAND (1/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Current: accepts any string
+- Need: reject whitespace-only strings
+- File: src/invar/core/parser.py
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → SPECIFY (2/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+@pre(lambda source, path: len(source.strip()) > 0)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → BUILD (3/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Implementation...]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → VALIDATE (4/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ guard PASS | 0 errors, 1 warning
+
+✓ Final: guard PASS | 0 errors, 1 warning
+```
+<!--/invar:skill-->
+
+<!--invar:extensions-->
+<!-- ========================================================================
+     EXTENSIONS REGION - USER EDITABLE
+     Add project-specific extensions here. This section is preserved on update.
+
+     Examples of what to add:
+     - Project-specific validation steps
+     - Custom commit message formats
+     - Additional tool integrations
+     - Team-specific workflows
+     ======================================================================== -->
+<!--/invar:extensions-->