invar-tools 1.4.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

invar/templates/config/CLAUDE.md.jinja

@@ -12,6 +12,24 @@
 | **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 }}"-->
@@ -19,28 +37,13 @@
 
 > **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion requirements.
 
-## Check-In (DX-54)
+## Check-In
 
-Your first message MUST display:
+> See [INVAR.md#check-in](./INVAR.md#check-in-required) for full protocol.
 
-```
-✓ Check-In: [project] | [branch] | [clean/dirty]
-```
+**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.
+**Actions:** Read `.invar/context.md`, then show status. Do NOT run guard at Check-In.
 
 ---
 
@@ -79,6 +82,14 @@ src/{project}/
 | 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 |
@@ -86,8 +97,11 @@ src/{project}/
 | 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/project-additions.md | User | Yes | Project rules → injected into CLAUDE.md |
 | .invar/examples/ | Invar | No | **Must read:** Core/Shell patterns, workflow |
 
+> **Before writing code:** Check Task Router in `.invar/context.md`
+
 ## Visible Workflow (DX-30)
 
 For complex tasks (3+ functions), show 3 checkpoints in TodoList:
@@ -158,18 +172,26 @@ Guard triggers `review_suggested` for: security-sensitive files, escape hatches
 
 ## Workflow Routing (MANDATORY)
 
-When user message contains these triggers, you MUST invoke the corresponding skill:
+When user message contains these triggers, you MUST use the **Skill tool** to invoke the skill:
+
+| Trigger Words | Skill Tool Call | Notes |
+|---------------|-----------------|-------|
+| "review", "review and fix" | `Skill(skill="review")` | Adversarial review with fix loop |
+| "implement", "add", "fix", "update" | `Skill(skill="develop")` | Unless in review context |
+| "why", "explain", "investigate" | `Skill(skill="investigate")` | Research mode, no code changes |
+| "compare", "should we", "design" | `Skill(skill="propose")` | Decision facilitation |
+
+**⚠️ CRITICAL: You must call the Skill tool, not just follow the workflow mentally.**
 
-| 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 |
+The Skill tool reads `.claude/skills/<skill>/SKILL.md` which contains:
+- Detailed phase instructions (USBV breakdown)
+- Error handling rules
+- Timeout policies
+- Incremental development patterns (DX-63)
 
 **Violation check (before writing ANY code):**
-- "Am I in a workflow?"
-- "Did I invoke the correct skill?"
+- "Did I call `Skill(skill="...")`?"
+- "Am I following the SKILL.md instructions?"
 
 ---
 
@@ -204,7 +226,7 @@ enters /review. Say "skip" to bypass.
 <!--invar:project-->
 <!-- ========================================================================
      PROJECT REGION - INVAR PROJECT ONLY
-     This section is populated by .invar/project-additions.md via sync-self.
+     This section is populated by .invar/project-additions.md via `invar dev sync`.
      For other projects, this region remains empty.
      ======================================================================== -->
 <!--/invar:project-->
@@ -213,7 +235,7 @@ enters /review. Say "skip" to bypass.
 <!-- ========================================================================
      USER REGION - EDITABLE
      Add your team conventions and project-specific rules below.
-     This section is preserved across invar update and sync-self.
+     This section is preserved across `invar update` and `invar dev sync`.
      ======================================================================== -->
 <!--/invar:user-->
 

invar/templates/config/context.md.jinja

@@ -27,6 +27,20 @@
 {% endif -%}
 - Final must show: `✓ Final: guard PASS | ...`
 
+## Task Router (DX-62)
+
+<!-- Before writing code, check this table -->
+
+| If you are about to... | STOP and read first |
+|------------------------|---------------------|
+| Write code in `core/` | `.invar/examples/contracts.py` |
+| Write code in `shell/` | `.invar/examples/core_shell.py` |
+| Add `@pre`/`@post` contracts | `.invar/examples/contracts.py` |
+| Use functional patterns | `.invar/examples/functional.py` |
+| Implement a feature | `.invar/examples/workflow.md` |
+
+**Rule:** Match found above? Read the file BEFORE writing code.
+
 ## Self-Reminder
 
 <!-- DX-54: AI should re-read this file periodically -->

invar/templates/protocol/INVAR.md

@@ -267,6 +267,7 @@ invar guard              # Full: static + doctests + CrossHair + Hypothesis
 invar guard --static     # Static only (quick debug, ~0.5s)
 invar guard --changed    # Modified files only
 invar guard --coverage   # Collect branch coverage
+invar guard -c           # Contract coverage only (DX-63)
 invar sig <file>         # Show contracts + signatures
 invar map --top 10       # Most-referenced symbols
 invar rules              # List all rules with detection/hints (JSON)

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

@@ -17,7 +17,8 @@ _invar:
 
 Before any workflow action:
 1. Read `.invar/context.md` (especially Key Rules section)
-2. Display routing announcement
+2. **Check Task Router** — read examples before coding in `core/` or `shell/`
+3. Display routing announcement
 
 ### Routing Announcement
 
@@ -71,6 +72,55 @@ def calculate(x: int) -> int:
     ...  # Implementation comes in BUILD
 ```
 
+#### Function-Level Gates (DX-63)
+
+When creating new modules, use **incremental development**:
+
+1. Create ONE file
+2. Write contracts for all functions (body = `...`)
+{% if syntax == "mcp" -%}
+3. Run `invar_guard(contracts_only=true)` to verify coverage
+{% else -%}
+3. Run `invar guard -c <file>` to verify coverage
+{% endif -%}
+4. Implement functions
+{% if syntax == "mcp" -%}
+5. Run `invar_guard(changed=true)`
+{% else -%}
+5. Run `invar guard --changed`
+{% endif -%}
+6. Proceed to next file
+
+❌ Do NOT create multiple file skeletons at once
+❌ Do NOT "structure first, fill later"
+
+**TodoList Pattern: Interleaved SPECIFY/BUILD**
+
+For each function:
+```
+□ [SPECIFY] Write contract for validate_input
+□ [BUILD] Implement validate_input
+□ [SPECIFY] Write contract for process_data
+□ [BUILD] Implement process_data
+```
+
+NOT:
+```
+□ [SPECIFY] Write all contracts
+□ [BUILD] Implement all functions
+```
+
+**Violation Self-Check** — Before writing ANY implementation code:
+1. "Have I written the contract for THIS function?"
+2. "Have I shown it in my response?"
+{% if syntax == "mcp" -%}
+3. "Have I run `invar_guard(contracts_only=true)`?"
+{% else -%}
+3. "Have I run `invar guard -c`?"
+{% endif -%}
+
+If any NO → Stop. Write contract first.
+
 ### 3. BUILD
 
 **For complex tasks:** Enter Plan Mode first, get user approval.

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

@@ -1,29 +1,91 @@
 ---
 name: review
-description: Adversarial code review with fix loop. Use after development, when Guard reports review_suggested, or user explicitly requests review. Finds issues that automated verification misses. Supports isolated mode (sub-agent) and quick mode (same context).
+description: Fault-finding code review with REJECTION-FIRST mindset and AUTO-LOOP. Code is GUILTY until proven INNOCENT. Automatically cycles Reviewer→Fixer→Reviewer until quality_met or max_rounds. No human confirmation needed between roles.
 _invar:
   version: "{{ version }}"
   managed: skill
 ---
 <!--invar:skill-->
 
-# Review Mode
+# Review Mode (Fault-Finding with Auto-Loop)
 
 > **Purpose:** Find problems that Guard, doctests, and property tests missed.
-> **Mindset:** Adversarial. Your success is measured by problems found, not code approved.
+> **Mindset:** REJECTION-FIRST. Code is GUILTY until proven INNOCENT.
+> **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).
 
-## Adversarial Reviewer Persona
+## Auto-Loop Configuration
+
+```
+MAX_ROUNDS = 5          # Maximum review-fix cycles
+AUTO_TRANSITION = true  # No human confirmation between roles
+```
+
+## Prime Directive: Reject Until Proven Correct
+
+**You are the PROSECUTOR, not the defense attorney.**
+
+| Trap | Reality Check |
+|------|---------------|
+| "Seems fine" | You failed to find the bug |
+| "Makes sense" | You're rationalizing, not reviewing |
+| "Edge case is unlikely" | Edge cases ARE bugs |
+| "Comment explains it" | Comments don't fix code |
+| "Assessed as acceptable" | "Assessed" ≠ "Fixed" |
+
+## Role Separation (CRITICAL)
+
+**You play TWO distinct roles that cycle AUTOMATICALLY:**
+
+| Role | Allowed Actions | Forbidden |
+|------|-----------------|-----------|
+| **REVIEWER** | Find issues, judge fixes, declare quality_met | Write code, rationalize issues |
+| **FIXER** | Implement fixes only | Declare quality_met, dismiss issues |
+
+**Role Transition Markers (REQUIRED):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔍 REVIEWER [Round N] — Finding issues
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔧 FIXER [Round N] — Implementing fixes
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ REVIEWER [Round N] — Verifying fixes
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Quality Gate Authority
+
+**ONLY the Reviewer role can declare `quality_met`.**
+
+Before declaring exit:
+1. Re-read EVERY issue found
+2. For each issue, verify: "Is this ACTUALLY fixed, or did I rationalize it?"
+3. Ask: "Would I accept this excuse from someone else's code?"
+
+**Self-Check Questions:**
+- Did I write code AND declare quality_met? → Role confusion detected
+- Did I say "assessed" instead of "fixed"? → Rationalization detected
+- Did any MAJOR become a comment instead of code? → Fix failed
+
+## Fault-Finding Persona
 
 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
+- **Your own fixes may introduce new bugs**
 
 You ARE here to:
 - Find bugs, logic errors, edge cases
 - Challenge whether contracts have semantic value
 - Check if code matches contracts (not if code "seems right")
+- **RE-VERIFY fixes, not trust them**
 
 ## Entry Actions
 
@@ -117,46 +179,149 @@ These are checked by Guard or linters - don't duplicate:
 - Entry point thickness → Guard (entry_point_too_thick)
 - Escape hatch count → Guard (review_suggested)
 
-## Review-Fix Loop
+## Auto-Loop Workflow (NO HUMAN CONFIRMATION)
+
+**The loop runs AUTOMATICALLY until exit condition is met.**
 
 ```
-Round 1: Review → Find issues
-    ↓
-Fix CRITICAL + MAJOR (MINOR → backlog)
-    ↓
-Round 2: Re-review (if needed)
-    ↓
-Convergence check:
-- No CRITICAL/MAJOR → Exit ✓
-- No improvement → Exit (warn)
-- Round >= 3 → Exit (max)
+┌─────────────────────────────────────────────────────────────────┐
+│  START: round = 1, issues = []                                  │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │  🔍 REVIEWER [Round N]                                  │    │
+│  │    1. Find ALL issues (don't stop at first)            │    │
+│  │    2. Classify: CRITICAL / MAJOR / MINOR               │    │
+│  │    3. Add to issues table                              │    │
+│  │    4. IF no CRITICAL/MAJOR → quality_met, EXIT         │    │
+│  │    5. ELSE → AUTO-TRANSITION to FIXER                  │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                         ↓ (automatic)                           │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │  🔧 FIXER [Round N]                                     │    │
+│  │    1. Fix EACH CRITICAL/MAJOR issue with CODE          │    │
+│  │    2. Run invar_guard() after fixes                    │    │
+│  │    3. NO declaring quality_met (forbidden)             │    │
+│  │    4. AUTO-TRANSITION back to REVIEWER                 │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                         ↓ (automatic)                           │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │  ✅ REVIEWER [Round N] — Verification                   │    │
+│  │    1. Re-verify EACH fix:                              │    │
+│  │       - Is fix CODE or just COMMENT?                   │    │
+│  │       - Does fix actually address issue?               │    │
+│  │       - Did fix introduce new issues?                  │    │
+│  │    2. Update verification table                        │    │
+│  │    3. IF all CRITICAL/MAJOR fixed → quality_met, EXIT  │    │
+│  │    4. IF round >= MAX_ROUNDS → max_rounds, EXIT        │    │
+│  │    5. IF no progress → no_improvement, EXIT            │    │
+│  │    6. ELSE → round++, LOOP to REVIEWER [Round N+1]     │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                 │
+│  EXIT: Generate final report                                    │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
+## Loop State Tracking
+
+**Maintain this state throughout the loop:**
+
+```markdown
+## Review State
+- **Round:** N / MAX_ROUNDS
+- **Role:** REVIEWER | FIXER
+- **Issues Found:** [count]
+- **Issues Fixed:** [count]
+- **Guard Status:** PASS | FAIL
+```
+
+## Verification Table (Updated Each Round)
+
+| Issue ID | Severity | Round Found | Status | Evidence |
+|----------|----------|-------------|--------|----------|
+| MAJOR-1 | MAJOR | 1 | ✅ Fixed (R2) | Code change at line X |
+| MAJOR-2 | MAJOR | 1 | ❌ Unfixed | Fix attempted but failed |
+| MAJOR-3 | MAJOR | 2 | 🔄 New | Found during re-verification |
+| ... | ... | ... | ... | ... |
+
+**Status Legend:**
+- ✅ Fixed (RN) — Actually fixed with code in round N
+- ❌ Unfixed — Fix failed or was just a comment
+- 🔄 New — Found during re-verification (new issue)
+- ⏭️ Backlog — MINOR, deferred to later
+
+If ANY ❌ exists for CRITICAL/MAJOR after MAX_ROUNDS → quality_not_met
+
 ## Severity Definitions
 
-| Level | Meaning | Examples |
-|-------|---------|----------|
-| CRITICAL | Security, data loss, crash | SQL injection, unhandled null |
-| MAJOR | Logic error, missing validation | Wrong calculation, no bounds |
-| MINOR | Style, documentation | Naming, missing docstring |
+| Level | Meaning | Examples | Exit Blocker? |
+|-------|---------|----------|---------------|
+| CRITICAL | Security, data loss, crash | SQL injection, unhandled null | **YES** |
+| MAJOR | Logic error, missing validation | Wrong calculation, no bounds | **YES** |
+| MINOR | Style, documentation | Naming, missing docstring | No (backlog) |
+
+## Exit Conditions (Auto-Loop)
 
-## Exit Report
+**Exit triggers (checked automatically after each REVIEWER phase):**
+
+| Condition | Exit Reason | Result |
+|-----------|-------------|--------|
+| All CRITICAL/MAJOR fixed | `quality_met` | ✅ Ready for merge |
+| Round >= MAX_ROUNDS | `max_rounds` | ⚠️ Manual review needed |
+| No progress (same issues 2 rounds) | `no_improvement` | ❌ Architectural issue |
+| Guard fails after fix | Continue loop | 🔄 More fixes needed |
+
+**quality_met requires ALL of:**
+1. Zero CRITICAL issues remaining
+2. Zero MAJOR issues remaining (not "assessed", actually FIXED)
+3. Verification table completed with evidence for each fix
+4. Guard passes after all fixes
+
+**Automatic quality_not_met:**
+- Any MAJOR "fixed" with comment instead of code
+- Any issue marked "assessed" or "acceptable"
+- Fixer role declared quality_met (role violation)
+- Infinite loop detected (no progress)
+
+## Exit Report (Generated Automatically)
 
 ```markdown
-### Review Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 REVIEW COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Exit Reason:** quality_met | max_rounds | no_improvement
+**Total Rounds:** N / MAX_ROUNDS
+**Guard Status:** PASS | FAIL
+
+## Verification Table
+
+| Issue | Severity | Round | Status | Evidence |
+|-------|----------|-------|--------|----------|
+| MAJOR-1 | MAJOR | 1→2 | ✅ Fixed | Code at file.py:123 |
+| ... | ... | ... | ... | ... |
+
+## Statistics
+
+- Issues Found: X
+- Issues Fixed: Y
+- Fix Rate: Y/X (Z%)
+- New Issues from Fixes: N
+
+## Self-Check (Reviewer Final)
 
-**Rounds:** [N]
-**Exit reason:** quality_met | max_rounds | no_improvement
+- [x] All fixes are CODE, not comments
+- [x] No "assessed as acceptable" rationalizations
+- [x] Guard passes after all changes
+- [x] Role separation maintained throughout
 
-**Fixed:**
-- [list of fixed issues]
+## Recommendation
 
-**Remaining (MINOR - backlog):**
-- [list for later]
+- [x] Ready for merge (quality_met)
+- [ ] Needs manual review (max_rounds)
+- [ ] Architectural refactor needed (no_improvement)
 
-**Recommendation:**
-- [ ] Ready for merge
-- [ ] Needs more work: [issues]
+**MINOR (Backlog):**
+- [list deferred items]
 ```
 <!--/invar:skill-->
 <!--invar:extensions-->

{invar_tools-1.4.0.dist-info → invar_tools-1.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.4.0
+Version: 1.6.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
@@ -61,6 +61,10 @@ agents write code that's correct by construction—not by accident.
   <a href="#license"><img src="https://img.shields.io/badge/License-Apache%202.0%20%2B%20GPL--3.0-blue.svg" alt="License"></a>
 </p>
 
+<p align="center">
+  <a href="#why-invar"><img src="https://img.shields.io/badge/🤖_Dogfooding-Invar's_code_is_100%25_AI--generated_and_AI--verified_using_itself-8A2BE2?style=for-the-badge" alt="Dogfooding"></a>
+</p>
+
 ### What It Looks Like
 
 An AI agent, guided by Invar, writes code with formal contracts and built-in tests:
@@ -111,10 +115,10 @@ Guard passed.
 ┌───────────────────────────────────────────────────────────────────┐
 │  Your Project                                                     │
 │  ├── pyproject.toml                                               │
-│  │   └── dependencies = ["invar-runtime"]  ← Ships with code     │
+│  │   └── dependencies = ["invar-runtime"]  ← Ships with code      │
 │  │                                                                │
 │  └── Development (never enters production)                        │
-│      └── uvx invar-tools guard  ← Guides agents     │
+│      └── uvx invar-tools guard  ← Guides agents                   │
 └───────────────────────────────────────────────────────────────────┘
 ```
 
@@ -244,10 +248,10 @@ Guard provides fast feedback. Agent sees errors, fixes immediately:
 | **Symbolic** | CrossHair | ~30s | Mathematical proof of contracts |
 
 ```
-┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
+┌──────────┐   ┌───────────┐   ┌───────────┐   ┌────────────┐
 │ ⚡ Static │ → │ 🧪 Doctest│ → │ 🎲 Property│ → │ 🔬 Symbolic│
-│   ~0.5s  │   │   ~2s    │   │   ~10s   │   │   ~30s   │
-└──────────┘   └──────────┘   └──────────┘   └──────────┘
+│   ~0.5s  │   │   ~2s     │   │   ~10s    │   │   ~30s     │
+└──────────┘   └───────────┘   └───────────┘   └────────────┘
 ```
 
 ```
@@ -268,8 +272,8 @@ The USBV workflow forces "specify before implement":
 
 ```
 🔍 Understand  →  📝 Specify  →  🔨 Build  →  ✓ Validate
-      │              │             │            │
-   Context       Contracts       Code        Guard
+      │              │              │            │
+   Context        Contracts        Code        Guard
 ```
 
 Skill routing ensures agents enter through the correct workflow: