invar-tools 1.8.0__py3-none-any.whl → 1.11.0__py3-none-any.whl

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

@@ -1,146 +1,161 @@
 ---
 name: review
-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.
+description: Adversarial code review. Code is GUILTY until proven INNOCENT. Every round spawns isolated subagent reviewing FULL scope.
 _invar:
-  version: "{{ version }}"
+  version: "7.0"
   managed: skill
 ---
 <!--invar:skill-->
 
-# Review Mode (Fault-Finding with Auto-Loop)
+# Review Skill (Adversarial)
 
-> **Purpose:** Find problems that Guard, doctests, and property tests missed.
-> **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).
+## Mandatory Rules (MUST follow, NO exceptions)
 
-## Scope Boundaries
-
-**This skill IS for:**
-- Finding bugs and logic errors in existing code
-- Verifying contract semantic value
-- Auditing escape hatches
-- Security review
-
-**This skill is NOT for:**
-- Implementing new features → switch to `/develop`
-- Understanding how code works → switch to `/investigate`
-- Deciding on architecture → switch to `/propose`
-
-**Drift detection:** If you're writing significant new code (not fixes) → STOP, you're in wrong skill.
+1. **EVERY round MUST spawn isolated subagent** (Task tool with model=opus)
+2. **EVERY round reviews FULL scope** (all files, not just changes)
+3. **Code is GUILTY until proven INNOCENT**
+4. **NO user confirmation between rounds** — just do it
+5. **MAX_ROUNDS = 5**
 
-## Auto-Loop Configuration
-
-```
-MAX_ROUNDS = 5          # Maximum review-fix cycles
-AUTO_TRANSITION = true  # No human confirmation between roles
-```
+**Violation = Review Invalid.** If you skip subagent or review only changes, the review is worthless.
 
-## Prime Directive: Reject Until Proven Correct
+---
 
-**You are the PROSECUTOR, not the defense attorney.**
+## Scope Classification (DX-75)
 
-| 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" |
+**Before starting, classify the scope:**
 
-## Role Separation (CRITICAL)
+| Classification | Criteria | Strategy |
+|----------------|----------|----------|
+| **SMALL** | <5 files AND <1500 lines | THOROUGH (no enumeration) |
+| **MEDIUM** | 5-10 files OR 1500-5000 lines | HYBRID (enum + open) |
+| **LARGE** | >10 files OR >5000 lines | CHUNKED (parallel subagents) |
 
-**You play TWO distinct roles that cycle AUTOMATICALLY:**
+**Why different strategies?**
+- SMALL: Pre-enumeration causes "checklist mentality" — you only verify listed items, miss variants
+- LARGE: Without enumeration, attention drifts — later files get less scrutiny
 
-| 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):**
+## Strategy: THOROUGH (SMALL scope)
 
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🔍 REVIEWER [Round N] — Finding issues
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🔧 FIXER [Round N] — Implementing fixes
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ REVIEWER [Round N] — Verifying fixes
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+┌─────────────────────────────────────────────────────────────┐
+│  THOROUGH STRATEGY (for SMALL scope)                        │
+│  ───────────────────────────────────────────────────────────│
+│                                                             │
+│  ⚠️ DO NOT pre-enumerate issues or patterns                 │
+│  ⚠️ DO NOT use grep/sig to "find issues first"              │
+│                                                             │
+│  Instead:                                                   │
+│  1. Read each file COMPLETELY, line by line                 │
+│  2. Apply checklist A-G as you read                         │
+│  3. Trust your judgment to find issues                      │
+│  4. Look for VARIANTS and EDGE CASES                        │
+│                                                             │
+│  Why: Pre-enumeration narrows focus to known patterns.      │
+│  Small scope = you CAN read everything thoroughly.          │
+│  This finds issues that pattern matching misses.            │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-## 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
+## Strategy: HYBRID (MEDIUM scope)
 
-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
-
-### Context Refresh (DX-54)
-
-Before any workflow action:
-1. Read `.invar/context.md` (especially Key Rules section)
-2. Display routing announcement
+```
+┌─────────────────────────────────────────────────────────────┐
+│  HYBRID STRATEGY (for MEDIUM scope)                         │
+│  ───────────────────────────────────────────────────────────│
+│                                                             │
+│  Phase 0: ENUMERATE (Main Agent)                            │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Use grep/invar_sig to find:                        │   │
+│  │  - All @pre/@post contracts                         │   │
+│  │  - All @invar:allow escape hatches                  │   │
+│  │  - Hardcoded strings (secrets?)                     │   │
+│  │  - subprocess/exec/eval calls                       │   │
+│  │  - bare except clauses                              │   │
+│  │  Create issue_map with file:line for each           │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  Phase 1: GUIDED REVIEW (Isolated Subagent)                 │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Pass issue_map to subagent                         │   │
+│  │  Subagent verifies each item                        │   │
+│  │  Reports: "Checked N/M items from issue_map"        │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  Phase 2: OPEN DISCOVERY (Same Subagent)                    │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  "Now forget the issue_map.                         │   │
+│  │   Look for issues NOT in the map:                   │   │
+│  │   - Variants of listed patterns                     │   │
+│  │   - Logic errors                                    │   │
+│  │   - Edge cases"                                     │   │
+│  │  Reports: "Found N additional issues"               │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
 
-### Routing Announcement
+## Strategy: CHUNKED (LARGE scope)
 
 ```
-📍 Routing: /review — [trigger, e.g. "review_suggested", "user requested review"]
-   Task: [review scope summary]
+┌─────────────────────────────────────────────────────────────┐
+│  CHUNKED STRATEGY (for LARGE scope)                         │
+│  ───────────────────────────────────────────────────────────│
+│                                                             │
+│  1. Split files into chunks of ~3-5 files each              │
+│                                                             │
+│  2. For each chunk (can be parallel):                       │
+│     - Spawn isolated subagent                               │
+│     - Use HYBRID strategy within chunk                      │
+│                                                             │
+│  3. Cross-chunk analysis:                                   │
+│     - Check cross-file dependencies                         │
+│     - Check API consistency                                 │
+│                                                             │
+│  4. Merge all findings, deduplicate                         │
+│                                                             │
+│  Why: Prevents "attention fatigue" on file 8+ of 15.        │
+│  Each chunk gets fresh attention.                           │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-## Mode Selection
+---
 
-### Check Guard Output
+## 2-Step Loop (MANDATORY workflow)
 
-Look for `review_suggested` warning:
 ```
-WARNING: review_suggested - High escape hatch count
-WARNING: review_suggested - Security-sensitive path detected
-WARNING: review_suggested - Low contract coverage
+┌─────────────────────────────────────────────────────────────┐
+│  Round N:                                                   │
+│                                                             │
+│  1. REVIEWER [Subagent] ─────────────────────────────────── │
+│     • Spawn NEW isolated agent (Task tool)                  │
+│     • Use strategy based on scope classification            │
+│     • Review ALL files in scope (full checklist A-G)        │
+│     • Return: issues[] or APPROVED                          │
+│                                                             │
+│  2. FIXER [Main Agent] ──────────────────────────────────── │
+│     • Fix CRITICAL/MAJOR issues with CODE                   │
+│     • Run invar_guard()                                     │
+│     • Cannot declare quality_met                            │
+│                                                             │
+│  → Loop until: APPROVED OR max_rounds OR no_progress        │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-### Select Mode
+**Why new subagent each round?**
+- Main agent has context contamination from fixing
+- "Fresh eyes" impossible in same context
+- Round 2+ drifts to "verify my fixes" not "find problems"
 
-| Condition | Mode |
-|-----------|------|
-| `review_suggested` present | **Isolated** (spawn sub-agent) |
-| `--isolated` flag | **Isolated** |
-| Default (no trigger) | **Quick** (same context) |
+---
 
-## Review Checklist
+## Review Checklist (apply to ALL files)
 
-> **Principle:** Only items requiring semantic judgment. Mechanical checks are handled by Guard.
+> **Principle:** Only items requiring semantic judgment. Mechanical checks handled by Guard.
 
 ### 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)`
@@ -151,203 +166,160 @@ WARNING: review_suggested - Low contract coverage
 - [ ] Are boundary conditions explicit in contracts?
 
 ### B. Doctest Coverage
-- [ ] Do doctests cover normal cases?
-- [ ] Do doctests cover boundary cases?
-- [ ] Do doctests cover error cases?
+
+- [ ] Do doctests cover normal, boundary, and 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?
-- [ ] Is there dead code or unreachable branches?
 
 ### 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
+### G. Error Handling
+
 - [ ] 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 Guard)
-
-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)
-- Escape hatch count → Guard (review_suggested)
+---
 
-## Auto-Loop Workflow (NO HUMAN CONFIRMATION)
+## Subagent Prompt Templates
 
-**The loop runs AUTOMATICALLY until exit condition is met.**
+### THOROUGH (SMALL scope)
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│  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                                    │
-└─────────────────────────────────────────────────────────────────┘
+You are an independent Adversarial Code Reviewer.
+
+RULES:
+1. Code is GUILTY until proven INNOCENT
+2. You did NOT write this code — no emotional attachment
+3. Find reasons to REJECT, not accept
+4. Be specific: file:line + concrete fix
+
+STRATEGY: THOROUGH READING
+- Read each file COMPLETELY, line by line
+- DO NOT pre-scan for patterns — just READ
+- Look for VARIANTS and EDGE CASES
+- Trust your judgment
+
+SCOPE: [list all files]
+
+Apply checklist A-G to each file.
+
+OUTPUT FORMAT:
+## Verdict: APPROVED | NEEDS WORK | REJECTED
+## Critical Issues (must fix)
+| ID | File:Line | Issue | Fix |
+## Major Issues (should fix)
+| ID | File:Line | Issue | Fix |
+## Minor Issues (backlog)
+| ID | File:Line | Issue | Fix |
 ```
 
-## Loop State Tracking
+### HYBRID (MEDIUM scope)
 
-**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
 ```
+You are an independent Adversarial Code Reviewer.
+
+RULES:
+1. Code is GUILTY until proven INNOCENT
+2. You did NOT write this code — no emotional attachment
+3. Find reasons to REJECT, not accept
+4. Be specific: file:line + concrete fix
+
+STRATEGY: HYBRID (two passes)
 
-## Verification Table (Updated Each Round)
+PASS 1 - GUIDED:
+Using this issue_map, verify each potential issue:
+[issue_map from Phase 0]
 
-| 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 |
-| ... | ... | ... | ... | ... |
+Report: "Verified X/Y items from issue_map"
 
-**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
+PASS 2 - OPEN DISCOVERY:
+Now FORGET the issue_map. Read the code fresh.
+Look for issues NOT in the map:
+- Variants of listed patterns
+- Logic errors
+- Edge cases
 
-If ANY ❌ exists for CRITICAL/MAJOR after MAX_ROUNDS → quality_not_met
+Report: "Found N additional issues not in issue_map"
 
-## Severity Definitions
+SCOPE: [list all files]
 
-| 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) |
+OUTPUT FORMAT:
+## Verdict: APPROVED | NEEDS WORK | REJECTED
+## From Issue Map (Pass 1)
+| ID | File:Line | Issue | Fix |
+## Additional Findings (Pass 2)
+| ID | File:Line | Issue | Fix |
+```
 
-## Exit Conditions (Auto-Loop)
+---
 
-**Exit triggers (checked automatically after each REVIEWER phase):**
+## Exit Conditions
 
 | 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
+| Subagent returns APPROVED | `quality_met` | Ready for merge |
+| round >= 5 | `max_rounds` | Manual review needed |
+| Same issues 2 rounds | `no_improvement` | Architectural issue |
+
+---
+
+## Exit Report
+
+```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📋 REVIEW COMPLETE
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Exit Reason:** quality_met | max_rounds | no_improvement
-**Total Rounds:** N / MAX_ROUNDS
-**Guard Status:** PASS | FAIL
-
-## Verification Table
+**Scope:** SMALL | MEDIUM | LARGE
+**Strategy:** THOROUGH | HYBRID | CHUNKED
+**Exit:** quality_met | max_rounds | no_improvement
+**Rounds:** N / 5
+**Guard:** PASS | FAIL
 
+## Issues Table
 | Issue | Severity | Round | Status | Evidence |
-|-------|----------|-------|--------|----------|
-| MAJOR-1 | MAJOR | 1→2 | ✅ Fixed | Code at file.py:123 |
-| ... | ... | ... | ... | ... |
 
-## Statistics
+## Round Summary
+| Round | Found | Fixed |
 
-- Issues Found: X
-- Issues Fixed: Y
-- Fix Rate: Y/X (Z%)
-- New Issues from Fixes: N
+✓ Final: guard PASS | X errors, Y warnings
+```
 
-## Self-Check (Reviewer Final)
+---
 
-- [x] All fixes are CODE, not comments
-- [x] No "assessed as acceptable" rationalizations
-- [x] Guard passes after all changes
-- [x] Role separation maintained throughout
+## Scope Boundaries
 
-## Recommendation
+**IS for:** Finding bugs, verifying contracts, security review
+**NOT for:** New features → /develop | Understanding → /investigate
 
-- [x] Ready for merge (quality_met)
-- [ ] Needs manual review (max_rounds)
-- [ ] Architectural refactor needed (no_improvement)
+## Excluded (Covered by Guard)
 
-**MINOR (Backlog):**
-- [list deferred items]
-```
-<!--/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 security review checklists
-     - Custom severity definitions
-     - Domain-specific code patterns to check
-     - Team code review standards
-     ======================================================================== -->
+Don't duplicate mechanical checks:
+- Core/Shell separation → Guard
+- Missing contracts → Guard
+- File/function size → Guard
+
+<!--/invar:skill--><!--invar:extensions-->
+<!-- User extensions preserved on update -->
 <!--/invar:extensions-->