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

invar/templates/commands/{review.md → audit.md}

@@ -1,73 +1,14 @@
-# Code Review (Reviewer Role)
+# Audit
 
-## 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.
+Read-only code review. Reports issues without fixing them.
 
 ---
 
-## Quick Mode
-
-**Use when:** No `review_suggested` trigger, routine review needed.
+## Behavior
 
-Proceed with same-context review below.
+1. Analyze code for issues (style, bugs, security, architecture)
+2. Report findings with file:line references
+3. **Do NOT make any changes** - report only
 
 ---
 
@@ -149,7 +90,7 @@ You ARE here to:
 
 ---
 
-## Excluded (Covered by Tools)
+## Excluded (Covered by Guard)
 
 These are checked by Guard or linters - don't duplicate:
 - Core/Shell separation → Guard (forbidden_import, impure_call)
@@ -157,7 +98,6 @@ These are checked by Guard or linters - don't duplicate:
 - 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)
 
 ---
@@ -166,11 +106,11 @@ These are checked by Guard or linters - don't duplicate:
 
 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 |
+| Severity | Meaning |
+|----------|---------|
+| **CRITICAL** | Must fix before completion |
+| **MAJOR** | Fix or provide written justification |
+| **MINOR** | Optional, can defer |
 
 ```markdown
 ### [CRITICAL/MAJOR/MINOR] Issue Title
@@ -178,22 +118,20 @@ For each issue found, use severity levels:
 **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)
+**Suggestion:** How to fix (but don't implement)
 ```
 
 ---
 
-## Instructions Summary
+## Instructions
 
-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
+1. Run `invar guard --changed` to see current state
+2. Go through each checklist category
+3. For each issue, determine severity (CRITICAL/MAJOR/MINOR)
+4. Report with structured format above
+5. Be thorough and adversarial
 
-**Remember:** You are READ-ONLY. Report issues, don't fix them directly.
+**Remember:** You are READ-ONLY. Report issues, don't fix them.
 
 ---
 

invar/templates/commands/guard.md

@@ -0,0 +1,77 @@
+# Guard
+
+Run Invar verification on the project and report results.
+
+---
+
+## Behavior
+
+Execute `invar_guard()` and report:
+- Pass/fail status
+- Error count with details
+- Warning count with details
+
+**Do NOT fix issues** - just report verification results.
+
+---
+
+## When to Use
+
+- Quick verification check
+- Before committing changes
+- After pulling changes
+- To see current project health
+
+---
+
+## Execution
+
+Run verification:
+
+```
+invar_guard(changed=true)
+```
+
+Or for full project verification:
+
+```
+invar_guard()
+```
+
+---
+
+## Report Format
+
+```
+## Guard Results
+
+**Status:** PASS / FAIL
+**Errors:** N
+**Warnings:** N
+
+### Errors (if any)
+
+| Rule | File | Line | Message |
+|------|------|------|---------|
+| missing_contract | src/foo.py | 42 | Function 'bar' has no @pre/@post |
+
+### Warnings (if any)
+
+| Rule | File | Line | Message |
+|------|------|------|---------|
+| function_size | src/baz.py | 15 | Function exceeds 50 lines |
+```
+
+---
+
+## Next Steps
+
+After reporting results:
+- If PASS: No action needed
+- If FAIL: User decides whether to fix issues
+
+**Remember:** You are READ-ONLY. Report results, don't fix them.
+
+---
+
+Now run verification on the current project.

invar/templates/config/CLAUDE.md.jinja

@@ -0,0 +1,206 @@
+<!--invar:managed version="{{ version }}"-->
+# Project Development Guide
+
+> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion requirements.
+
+## Check-In (DX-54)
+
+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
+
+Example:
+```
+✓ Check-In: MyProject | main | clean
+```
+
+**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.
+
+---
+
+## 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 |
+
+## Documentation Structure
+
+| File | Owner | Edit? | Purpose |
+|------|-------|-------|---------|
+| INVAR.md | Invar | No | Protocol (`invar update` to sync) |
+| CLAUDE.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 |
+
+## 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 status, integration status
+```
+
+**BUILD is internal work** — not shown in TodoList.
+
+**Show contracts before code.** See `.invar/examples/workflow.md` for full example.
+
+## Phase Visibility (DX-51)
+
+Each USBV phase transition requires a visible header:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → SPECIFY (2/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Three-layer visibility:**
+- **Skill** (`/develop`) — Routing announcement
+- **Phase** (`SPECIFY 2/4`) — Phase header (this section)
+- **Tasks** — TodoWrite items
+
+Phase headers are SEPARATE from TodoWrite. Phase = where you are; TodoWrite = what to do.
+
+---
+
+## Context Management (DX-54)
+
+Re-read `.invar/context.md` when:
+1. Entering any workflow (/develop, /review, etc.)
+2. Completing a TodoWrite task (before moving to next)
+3. Conversation exceeds ~15-20 exchanges
+4. Unsure about project rules or patterns
+
+**Refresh is transparent** — do not announce "I'm refreshing context."
+Only show routing announcements when entering workflows.
+
+---
+
+## Commands (User-Invokable)
+
+| Command | Purpose |
+|---------|---------|
+| `/audit` | Read-only code review (reports issues, no fixes) |
+| `/guard` | Run Invar verification (reports results) |
+
+## Skills (Agent-Invoked)
+
+| Skill | Triggers | Purpose |
+|-------|----------|---------|
+| `/investigate` | "why", "explain", vague tasks | Research mode, no code changes |
+| `/propose` | "should we", "compare" | Decision facilitation |
+| `/develop` | "add", "fix", "implement" | USBV implementation workflow |
+| `/review` | After /develop, `review_suggested` | Adversarial review with fix loop |
+
+**Note:** Skills are invoked by agent based on context. Use `/audit` for user-initiated review.
+
+Guard triggers `review_suggested` for: security-sensitive files, escape hatches >= 3, contract coverage < 50%.
+
+---
+
+## Workflow Routing (MANDATORY)
+
+When user message contains these triggers, you MUST invoke the corresponding skill:
+
+| Trigger Words | Skill | Notes |
+|---------------|-------|-------|
+| "review", "review and fix" | `/review` | Adversarial review with fix loop |
+| "implement", "add", "fix", "update" | `/develop` | Unless in review context |
+| "why", "explain", "investigate" | `/investigate` | Research mode, no code changes |
+| "compare", "should we", "design" | `/propose` | Decision facilitation |
+
+**Violation check (before writing ANY code):**
+- "Am I in a workflow?"
+- "Did I invoke the correct skill?"
+
+---
+
+## Routing Control (DX-42)
+
+Agent announces routing decision before entering any workflow:
+
+```
+📍 Routing: /[skill] — [trigger or reason]
+   Task: [summary]
+```
+
+**User can redirect with natural language:**
+- "wait" / "stop" — pause and ask for direction
+- "just do it" — proceed with /develop
+- "let's discuss" — switch to /propose
+- "explain first" — switch to /investigate
+
+**Simple task optimization:** For simple tasks (single file, clear target, <50 lines), agent may offer:
+
+```
+📊 Simple task. Auto-orchestrate? [Y/N]
+```
+
+- Y → Full cycle without intermediate confirmations
+- N → Normal step-by-step workflow
+
+**Auto-review (DX-41):** When Guard outputs `review_suggested`, agent automatically
+enters /review. Say "skip" to bypass.
+<!--/invar:managed-->
+
+<!--invar:project-->
+<!-- ========================================================================
+     PROJECT REGION - INVAR PROJECT ONLY
+     This section is populated by .invar/project-additions.md via sync-self.
+     For other projects, this region remains empty.
+     ======================================================================== -->
+<!--/invar:project-->
+
+<!--invar:user-->
+<!-- ========================================================================
+     USER REGION - EDITABLE
+     Add your team conventions and project-specific rules below.
+     This section is preserved across invar update and sync-self.
+     ======================================================================== -->
+<!--/invar:user-->
+
+---
+
+*Generated by `invar init` v{{ version }}. Customize the user section freely.*

invar/templates/config/context.md.jinja

@@ -0,0 +1,92 @@
+# Project Context
+
+*Last updated: [DATE]*
+
+## Current State
+
+- Phase: [current development phase]
+- 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
+{% if syntax == "mcp" -%}
+- `invar_guard()` = static + doctests + CrossHair + Hypothesis
+{% else -%}
+- `invar guard` = static + doctests + CrossHair + Hypothesis
+{% endif -%}
+- 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]
+
+## Lessons Learned
+
+1. [Pitfall or issue] → [Solution or workaround]
+
+## Documentation Structure
+
+| File | Owner | Edit? |
+|------|-------|-------|
+| INVAR.md | Invar | No — use `invar update` |
+| CLAUDE.md | User | Yes |
+| .invar/context.md | User | Yes (this file) |
+| .invar/examples/ | Invar | No |
+
+**Decision rule:** Is this Invar protocol or project-specific?
+- Protocol content → Already in INVAR.md, don't duplicate
+- Project-specific → Add to CLAUDE.md or here
+
+## Technical Debt
+
+{% if syntax == "mcp" -%}
+*Run `invar_guard()` to check current status.*
+{% else -%}
+*Run `invar guard` to check current status.*
+{% endif %}
+
+| File | Warning | Priority |
+|------|---------|----------|
+| (none) | — | — |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| INVAR.md | Protocol reference (Invar-managed) |
+| CLAUDE.md | Project guide (customize freely) |
+| src/core/ | Pure business logic |
+| src/shell/ | I/O adapters |
+
+---
+
+*Update this file when: completing major tasks, making design decisions, discovering pitfalls.*

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

@@ -7,16 +7,19 @@ Follow the Invar Protocol in INVAR.md — includes Check-In, USBV workflow, and
 Your first message MUST display:
 
 ```
-✓ Check-In: guard PASS | top: <entry1>, <entry2>
+✓ Check-In: [project] | [branch] | [clean/dirty]
 ```
 
-Execute `invar guard --changed` 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.
-
 ## Final
 
 Your last message for an implementation task MUST display:

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,9 +5,9 @@ Reference patterns for @pre/@post contracts and doctests.
 Managed by Invar - do not edit directly.
 """
 
-# 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
 
 # =============================================================================
 # GOOD: Complete Contract
@@ -56,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.