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

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

@@ -1,8 +1,8 @@
 ---
 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: Fault-finding code review with REJECTION-FIRST mindset. Code is GUILTY until proven INNOCENT. Two-step loop (Review→Fix) with full-scope review each round. Use after development, when Guard reports review_suggested, or user explicitly requests review.
 _invar:
-  version: "{{ version }}"
+  version: "5.3"
   managed: skill
 ---
 <!--invar:skill-->
@@ -12,7 +12,97 @@ _invar:
 > **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).
+> **Workflow:** Two-step loop: Review → Fix → Review → Fix → ... (full scope each round, no separate "verify" step).
+
+## Depth Levels (DX-70)
+
+| Level | Context | Use Case |
+|-------|---------|----------|
+| (default) | Same context | Reviewing **others' code** only |
+| `--deep` | **Isolated agent** | Self-review, before merge, maximum objectivity |
+
+**Default:** Same context — **only appropriate for code you did NOT write**.
+
+**`--deep` mode:** Spawns isolated agent with no conversation history. **Required when:**
+- You wrote or modified the code being reviewed (self-review)
+- Before merge/PR
+- Maximum objectivity needed
+
+### ⚠️ Same-Context Review Limitations (CRITICAL)
+
+**Same-context review CANNOT be objective for self-written code because:**
+
+| Cognitive Bias | Effect |
+|----------------|--------|
+| **Intent over code** | You "know" what it's supposed to do, so you don't see what it actually does |
+| **Context memory** | You "remember" reading code, so you skip re-reading carefully |
+| **Confirmation bias** | You look for "code works" evidence, not "code fails" evidence |
+| **Completion pressure** | Subconscious goal becomes "finish review" not "find bugs" |
+
+**Evidence:** In DX-71 review, same-context missed 2 CRITICAL + 4 MAJOR issues that
+isolated agent found immediately. "Fresh eyes" claims don't work in same context.
+
+### Mandatory Self-Review Detection (DX-72)
+
+**Before starting review, you MUST check:**
+
+```
+If ANY file in review scope was edited by agent this session:
+┌──────────────────────────────────────────────────────────────┐
+│ 🚨 SELF-REVIEW DETECTED — Isolation Required                 │
+│                                                              │
+│ You modified files in the review scope this session.         │
+│ Same-context review has proven cognitive blind spots.        │
+│                                                              │
+│ Options:                                                     │
+│ [1] Use --deep (RECOMMENDED) — Spawn isolated agent          │
+│ [2] Acknowledge risk — User explicitly accepts limitations   │
+│                                                              │
+│ If user says "continue" or "quick review":                   │
+│ → Proceed but add WARNING to final report                    │
+│ → Report MUST state: "Self-review without isolation"         │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Default action:** If user doesn't specify, use `--deep` for self-review.
+
+### --deep Mode Execution
+
+When `--deep` is selected:
+
+1. Collect minimal inputs:
+   - Files to review
+   - Contracts (if available)
+   - Test files (if available)
+
+2. Spawn Task agent with:
+   - **Adversarial Code Reviewer persona** (see Appendix)
+   - NO conversation history
+   - Only the collected inputs
+
+3. Isolated agent returns structured review report
+
+4. Main agent fixes issues (if any)
+
+5. **CRITICAL: Spawn NEW isolated agent for Round 2+ Review**
+
+### --deep Mode Loop (MANDATORY)
+
+```
+while not quality_met:
+    report = spawn_NEW_isolated_reviewer(files)  # 每轮新 agent
+    if report.has_critical_or_major:
+        main_agent.fix(report.issues)            # 主 agent 修复
+    else:
+        quality_met = True
+```
+
+**Why new agent each round?**
+- Main agent has context contamination from fixing
+- "Fresh eyes" cannot be achieved in same context
+- Round 2 in same context drifts to "verify my fixes" not "find problems"
+
+---
 
 ## Scope Boundaries
 
@@ -34,8 +124,12 @@ _invar:
 ```
 MAX_ROUNDS = 5          # Maximum review-fix cycles
 AUTO_TRANSITION = true  # No human confirmation between roles
+ASK_USER = never        # NEVER ask user, just do it
 ```
 
+**CRITICAL: After finding issues, IMMEDIATELY switch to FIXER role and fix them.**
+**DO NOT ask "Proceed with fixes?" or similar — just fix and continue.**
+
 ## Prime Directive: Reject Until Proven Correct
 
 **You are the PROSECUTOR, not the defense attorney.**
@@ -54,25 +148,23 @@ AUTO_TRANSITION = true  # No human confirmation between roles
 
 | Role | Allowed Actions | Forbidden |
 |------|-----------------|-----------|
-| **REVIEWER** | Find issues, judge fixes, declare quality_met | Write code, rationalize issues |
+| **REVIEWER** | Find issues (full scope), 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
+🔍 REVIEWER [Round N] — Full scope review
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🔧 FIXER [Round N] — Implementing fixes
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ REVIEWER [Round N] — Verifying fixes
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+**NO separate "Verify" step.** After Fix, go directly to next round's Review.
+
 ## Quality Gate Authority
 
 **ONLY the Reviewer role can declare `quality_met`.**
@@ -100,7 +192,87 @@ 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**
+
+## Fresh Eyes Mandate (Round 2+) — ENFORCED
+
+**For rounds after the first, you MUST adopt "fresh eyes" mindset:**
+
+> "I am a different reviewer who has never seen this code or the previous fixes."
+
+| Trap | Correction |
+|------|------------|
+| "I just fixed this" | Irrelevant. Review it like new code. |
+| "This was fine last round" | Maybe you missed something. Check again. |
+| "The fix looks correct" | That's FIXER thinking. Find what's WRONG. |
+
+### Why This Exists
+
+Round 2+ in the same context naturally drifts toward "verify my fixes" instead of
+"find all problems". This cognitive bias causes issues to slip through:
+- Attention focuses on recently-fixed areas
+- Brain skips content it "remembers" reading
+- Subconscious goal becomes "complete task" not "find bugs"
+
+### Mandatory Actions (Round 2+)
+
+**Before declaring quality_met, you MUST:**
+
+1. **RE-READ all files using Read tool**
+   ```
+   ❌ WRONG: Rely on context memory ("I already read this")
+   ✅ RIGHT: Call Read() for each file in scope, every round
+   ```
+
+2. **Systematic audit per code block** (for documentation/examples)
+   ```
+   For each code block:
+   - List all symbols USED (types, functions, classes)
+   - List all IMPORTS shown
+   - Verify: every used symbol has corresponding import
+   ```
+
+3. **Section-by-section explicit check**
+   ```
+   □ Section 1 checked
+   □ Section 2 checked
+   □ Section 3 checked
+   ... (every section, not "looks fine overall")
+   ```
+
+4. **Verbalize findings before exit**
+   ```
+   ❌ WRONG: "Verified fixes, looks good"
+   ✅ RIGHT: "Re-read 5 files, checked 23 sections, found 0 new issues"
+   ```
+
+### Round 2+ Workflow Diagram
+
+```
+FIXER [Round N] completes
+         ↓
+┌─────────────────────────────────────────┐
+│  REVIEWER [Round N+1] — MANDATORY STEPS │
+│                                         │
+│  1. Call Read() for EVERY file in scope │
+│     (Do NOT skip, do NOT rely on memory)│
+│                                         │
+│  2. For each file:                      │
+│     □ Check section by section          │
+│     □ Audit imports vs usage            │
+│     □ Look for issues MISSED before     │
+│                                         │
+│  3. Verbalize: "Read X files, checked   │
+│     Y sections, found Z issues"         │
+│                                         │
+│  4. Only THEN: EXIT CHECK               │
+└─────────────────────────────────────────┘
+```
+
+**Full scope means:**
+1. Re-run the ENTIRE checklist (A through G)
+2. Review ALL files in scope, not just recent fixes
+3. Check if fixes introduced NEW issues
+4. Look for issues you missed in previous rounds
 
 ## Entry Actions
 
@@ -119,7 +291,27 @@ Before any workflow action:
 
 ## Mode Selection
 
-### Check Guard Output
+### Step 1: Check Self-Review (MANDATORY)
+
+```python
+# Pseudo-code for self-review detection
+files_in_scope = get_review_scope()
+files_edited_this_session = get_agent_edits()
+
+if files_in_scope & files_edited_this_session:
+    # SELF-REVIEW DETECTED
+    if user_said("--deep") or user_said("deep review"):
+        mode = ISOLATED
+    elif user_said("quick") or user_said("continue"):
+        mode = SAME_CONTEXT
+        add_warning_to_report = True  # "Self-review without isolation"
+    else:
+        # Default: recommend --deep, wait for user choice
+        show_self_review_warning()
+        mode = ISOLATED  # Default to safe option
+```
+
+### Step 2: Check Guard Output
 
 Look for `review_suggested` warning:
 ```
@@ -128,25 +320,28 @@ WARNING: review_suggested - Security-sensitive path detected
 WARNING: review_suggested - Low contract coverage
 ```
 
-### Select Mode
+### Select Mode (Final Decision)
 
-| Condition | Mode |
-|-----------|------|
-| `review_suggested` present | **Isolated** (spawn sub-agent) |
-| `--isolated` flag | **Isolated** |
-| Default (no trigger) | **Quick** (same context) |
+| Condition | Mode | Notes |
+|-----------|------|-------|
+| Self-review detected | **Isolated** (default) | Unless user explicitly accepts risk |
+| `review_suggested` present | **Isolated** | Guard recommends isolation |
+| `--deep` flag | **Isolated** | User requested |
+| Others' code, no triggers | **Quick** (same context) | Only valid for non-self code |
 
 ## Review Checklist
 
 > **Principle:** Only items requiring semantic judgment. Mechanical checks are 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)`
 - [ ] Does @post verify meaningful output properties?
   - Bad: `@post(lambda result: result is not None)`
   - Good: `@post(lambda result: len(result) == len(input))`
+
 - [ ] Could someone implement correctly from contracts alone?
 - [ ] Are boundary conditions explicit in contracts?
 
@@ -194,21 +389,37 @@ These are checked by Guard or linters - don't duplicate:
 - Entry point thickness → Guard (entry_point_too_thick)
 - Escape hatch count → Guard (review_suggested)
 
-## Auto-Loop Workflow (NO HUMAN CONFIRMATION)
+## Auto-Loop Workflow (FULLY AUTOMATIC)
 
-**The loop runs AUTOMATICALLY until exit condition is met.**
+**The loop runs AUTOMATICALLY until exit condition is met. NO user interaction.**
+
+**Two-step cycle: Review → Fix → Review → Fix → ...**
+
+⚠️ **NEVER ask user:**
+- "Proceed with fixes?"
+- "Should I fix these?"
+- "Do you want me to continue?"
+
+**Just do it.** Find issues → Fix them → Review again → Repeat until done.
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │  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                  │    │
+│  │  🔍 REVIEWER [Round N] — Full Scope Review              │    │
+│  │    1. Apply FULL checklist (A-G) to ENTIRE scope       │    │
+│  │    2. Find ALL issues (don't stop at first)            │    │
+│  │    3. Classify: CRITICAL / MAJOR / MINOR               │    │
+│  │    4. Check previous fixes: CODE or just COMMENT?      │    │
+│  │    5. Check if fixes introduced NEW issues             │    │
+│  │    6. Update issues table                              │    │
+│  │                                                         │    │
+│  │    EXIT CHECK:                                          │    │
+│  │    - IF no CRITICAL/MAJOR found → quality_met, EXIT    │    │
+│  │    - IF round >= MAX_ROUNDS → max_rounds, EXIT         │    │
+│  │    - IF no progress (same issues 2 rounds) → EXIT      │    │
+│  │    - ELSE → AUTO-TRANSITION to FIXER                   │    │
 │  └─────────────────────────────────────────────────────────┘    │
 │                         ↓ (automatic)                           │
 │  ┌─────────────────────────────────────────────────────────┐    │
@@ -216,26 +427,20 @@ These are checked by Guard or linters - don't duplicate:
 │  │    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]     │    │
+│  │    4. round++                                           │    │
+│  │    5. AUTO-TRANSITION to REVIEWER [Round N+1]          │    │
 │  └─────────────────────────────────────────────────────────┘    │
+│                         ↓ (automatic, fresh eyes)               │
+│                    [LOOP BACK TO REVIEWER]                      │
 │                                                                 │
 │  EXIT: Generate final report                                    │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
+**Key change from v5.1:** No separate "Verify" step. Each round's Review is a
+full-scope audit with the same rigor as Round 1. This prevents the "verification
+mindset" trap where standards unconsciously lower after fixing.
+
 ## Loop State Tracking
 
 **Maintain this state throughout the loop:**
@@ -249,20 +454,25 @@ These are checked by Guard or linters - don't duplicate:
 - **Guard Status:** PASS | FAIL
 ```
 
-## Verification Table (Updated Each Round)
+## Issues 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 |
-| ... | ... | ... | ... | ... |
+| Issue ID | Severity | Round Found | Round Fixed | Status | Evidence |
+|----------|----------|-------------|-------------|--------|----------|
+| MAJOR-1 | MAJOR | 1 | 1 | ✅ Fixed | Code change at file.py:123 |
+| MAJOR-2 | MAJOR | 1 | - | ❌ Unfixed | Fix was comment, not code |
+| MAJOR-3 | MAJOR | 2 | - | 🆕 New | Found in Round 2 review |
+| MINOR-1 | MINOR | 1 | - | ⏭️ Backlog | Deferred (non-blocking) |
 
 **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
+- ✅ Fixed — Actually fixed with CODE (not comments)
+- ❌ Unfixed — Fix failed, was just a comment, or not addressed
+- 🆕 New — Found in a later round (fix may have introduced it, or missed earlier)
+- ⏭️ Backlog — MINOR, deferred to later (non-blocking)
+
+**Round 2+ Review MUST check:**
+1. Are previous ✅ Fixed items ACTUALLY fixed? (Re-verify with fresh eyes)
+2. Did fixes introduce NEW issues?
+3. Did we miss anything in earlier rounds?
 
 If ANY ❌ exists for CRITICAL/MAJOR after MAX_ROUNDS → quality_not_met
 
@@ -276,26 +486,28 @@ If ANY ❌ exists for CRITICAL/MAJOR after MAX_ROUNDS → quality_not_met
 
 ## Exit Conditions (Auto-Loop)
 
-**Exit triggers (checked automatically after each REVIEWER phase):**
+**Exit is checked at the START of each REVIEWER phase (before finding issues):**
 
 | Condition | Exit Reason | Result |
 |-----------|-------------|--------|
-| All CRITICAL/MAJOR fixed | `quality_met` | ✅ Ready for merge |
+| Round N Review finds 0 CRITICAL/MAJOR | `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
+1. Current round's FULL SCOPE review found zero CRITICAL/MAJOR
+2. All previous issues verified as fixed (with code, not comments)
+3. Guard passes
+4. Issues table complete with evidence
 
 **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)
+- Same CRITICAL/MAJOR persists for 2+ rounds
+
+**Important:** quality_met is declared when a Review round finds NO new issues,
+not when fixes are applied. This ensures the final state is actually reviewed.
 
 ## Exit Report (Generated Automatically)
 
@@ -306,29 +518,45 @@ If ANY ❌ exists for CRITICAL/MAJOR after MAX_ROUNDS → quality_not_met
 
 **Exit Reason:** quality_met | max_rounds | no_improvement
 **Total Rounds:** N / MAX_ROUNDS
+**Final Round Result:** 0 CRITICAL/MAJOR found (quality_met) | X issues remain
 **Guard Status:** PASS | FAIL
+**Review Mode:** Isolated | Same-context (self-review⚠️)
 
-## Verification Table
+## Issues Table
 
-| Issue | Severity | Round | Status | Evidence |
-|-------|----------|-------|--------|----------|
-| MAJOR-1 | MAJOR | 1→2 | ✅ Fixed | Code at file.py:123 |
-| ... | ... | ... | ... | ... |
+| Issue | Severity | Found | Fixed | Status | Evidence |
+|-------|----------|-------|-------|--------|----------|
+| MAJOR-1 | MAJOR | R1 | R1 | ✅ Fixed | Code at file.py:123 |
+| MAJOR-2 | MAJOR | R2 | R2 | ✅ Fixed | Added validation |
+| ... | ... | ... | ... | ... | ... |
 
-## Statistics
+## Round Summary
 
-- Issues Found: X
-- Issues Fixed: Y
-- Fix Rate: Y/X (Z%)
-- New Issues from Fixes: N
+| Round | Issues Found | Issues Fixed | New from Fixes |
+|-------|--------------|--------------|----------------|
+| 1 | 3 | 3 | 0 |
+| 2 | 1 | 1 | 0 |
+| 3 | 0 | - | - | ← quality_met
 
-## Self-Check (Reviewer Final)
+## Self-Check (Final Review Round)
 
+- [x] Applied FULL checklist (A-G) with fresh eyes
 - [x] All fixes are CODE, not comments
 - [x] No "assessed as acceptable" rationalizations
 - [x] Guard passes after all changes
 - [x] Role separation maintained throughout
 
+## Self-Review Warning (if applicable)
+
+⚠️ **This was a same-context self-review.** Cognitive biases may have caused
+issues to be missed. For higher confidence, run `--deep` review before merge.
+
+Known blind spots in self-review:
+- Exception handlers that silently lose data
+- Path traversal / security issues in user input
+- Edge cases in validation logic
+- Documentation-implementation mismatches
+
 ## Recommendation
 
 - [x] Ready for merge (quality_met)
@@ -338,8 +566,40 @@ If ANY ❌ exists for CRITICAL/MAJOR after MAX_ROUNDS → quality_not_met
 **MINOR (Backlog):**
 - [list deferred items]
 ```
-<!--/invar:skill-->
-<!--invar:extensions-->
+## Appendix: Adversarial Code Reviewer Persona
+
+Used in `--deep` mode (isolated agent):
+
+```
+You are an independent Adversarial Code Reviewer.
+
+CRITICAL 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 and actionable (file:line, concrete fix)
+5. Your job is to find bugs, not approve code
+
+INPUT YOU WILL RECEIVE:
+- Code files to review
+- Contracts (if available)
+- Test files (if available)
+
+INPUT YOU WILL NOT RECEIVE:
+- Development conversation history
+- Developer's explanations
+- Prior context about design decisions
+
+OUTPUT FORMAT:
+Produce structured Review Report with:
+1. Verdict: APPROVED / NEEDS WORK / REJECTED
+2. Critical issues (must fix)
+3. Major issues (should fix)
+4. Minor issues (nice to fix)
+5. Positive observations (what's done well)
+```
+
+<!--/invar:skill--><!--invar:extensions-->
 <!-- ========================================================================
      EXTENSIONS REGION - USER EDITABLE
      Add project-specific extensions here. This section is preserved on update.